bd-geo-address 0.1.1

package/README.md

@@ -0,0 +1,622 @@
+# bd-geo-address
+
+> Bangladesh address library — division/district/upazila/thana lookup, FHIR geocode resolution, Bangla name support, postal codes, geolocation. Zero dependencies. Works on Node.js, React, Next.js, Vue, Angular, NestJS, Deno and Bun.
+
+[![npm version](https://img.shields.io/npm/v/bd-geo-address.svg)](https://www.npmjs.com/package/bd-geo-address)
+[![npm downloads](https://img.shields.io/npm/dm/bd-geo-address.svg)](https://www.npmjs.com/package/bd-geo-address)
+[![license](https://img.shields.io/npm/l/bd-geo-address.svg)](./LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
+
+---
+
+## Installation
+
+```bash
+npm install bd-geo-address
+# or
+yarn add bd-geo-address
+# or
+pnpm add bd-geo-address
+```
+
+---
+
+## Quick Start
+
+### Name-Based API
+
+```ts
+import { districtsOf, upazilasOf, isUpazila, isThana, DivisionName } from "bd-geo-address"
+
+// All districts in Dhaka division
+districtsOf(DivisionName.Dhaka)
+// → ['Dhaka', 'Gazipur', 'Kishoreganj', 'Manikganj', 'Munshiganj', 'Narayanganj', ...]
+
+// Upazilas of Tangail district
+upazilasOf("Tangail")
+// → [{ upazila: 'Tangail Sadar', upazilaBn: 'টাঙ্গাইল সদর', district: 'Tangail', ... }, ...]
+
+// Correctly distinguishes upazilas from metropolitan thanas
+isUpazila("Savar")   // → true
+isUpazila("Gulshan") // → false  (Gulshan is a metropolitan thana)
+isThana("Gulshan")   // → true
+```
+
+### FHIR Code API
+
+```ts
+import { resolveCode, toAddressString, toShortAddress } from "bd-geo-address"
+
+// App stores FHIR geocode in the database, resolves at runtime
+const address = resolveCode("30262530")
+
+address?.formatted.en
+// → 'Kafrul, Dhaka North City Corporation, Dhaka, Dhaka Division'
+
+address?.formatted.bn
+// → 'কাফরুল, ঢাকা উত্তর সিটি কর্পোরেশন, ঢাকা, ঢাকা বিভাগ'
+
+toShortAddress("30262530")  // → 'Kafrul, Dhaka'
+```
+
+---
+
+## CommonJS Usage
+
+```js
+const { allDivision, districtsOf, resolveCode, DivisionName } = require("bd-geo-address")
+
+console.log(allDivision())
+// → ['Dhaka', 'Chattogram', 'Mymensingh', 'Khulna', 'Rajshahi', 'Rangpur', 'Sylhet', 'Barisal']
+
+console.log(resolveCode("30262530").formatted.short)
+// → 'Kafrul, Dhaka'
+```
+
+---
+
+## API Reference
+
+### Division
+
+```ts
+import {
+  allDivision, allDivisionBn,
+  divisionalDataOf, divisionalDataOfBn,
+  isValidDivision, isValidDivisionBn,
+} from "bd-geo-address"
+
+allDivision()
+// → ['Dhaka', 'Chattogram', 'Mymensingh', 'Khulna', 'Rajshahi', 'Rangpur', 'Sylhet', 'Barisal']
+
+allDivisionBn()
+// → ['ঢাকা', 'চট্টগ্রাম', 'ময়মনসিংহ', 'খুলনা', 'রাজশাহী', 'রংপুর', 'সিলেট', 'বরিশাল']
+
+divisionalDataOf("Sylhet")
+// → { districts: ['Sylhet', 'Sunamganj', 'Habiganj', 'Moulvibazar'], upazilas: [...] }
+
+divisionalDataOfBn("ঢাকা")
+// → { districts: [...], upazilas: [...] }
+
+isValidDivision("Dhaka")       // → true
+isValidDivision("InvalidName") // → false
+isValidDivisionBn("ঢাকা")      // → true
+```
+
+---
+
+### District
+
+```ts
+import {
+  allDistricts, allDistrictsBn,
+  districtsOf, districtsOfBn,
+  isValidDistrict, isValidDistrictBn,
+  getDivisionOfDistrict, getDivisionOfDistrictBn,
+} from "bd-geo-address"
+
+allDistricts()            // → all 64 district names in English
+allDistrictsBn()          // → all 64 district names in Bangla
+
+districtsOf("Dhaka")      // → ['Dhaka', 'Gazipur', 'Kishoreganj', ...]
+districtsOfBn("ঢাকা")     // → ['Dhaka', 'Gazipur', ...]
+
+isValidDistrict("Tangail")  // → true
+isValidDistrict("Savar")    // → false  (upazila, not a district)
+
+getDivisionOfDistrict("Tangail")      // → 'Dhaka'
+getDivisionOfDistrict("Cox's Bazar")  // → 'Chattogram'
+getDivisionOfDistrictBn("টাঙ্গাইল")   // → 'Dhaka'
+```
+
+---
+
+### Upazila
+
+```ts
+import {
+  allUpazila, allUpazilaNames, allUpazilaNamesBn,
+  upazilasOf, upazilasOfBn,
+  upazilaNamesOf, upazilaNamesOfBn,
+  upazilasOfDivision, upazilasOfDivisionBn,
+  upazilaNamesOfDivision, upazilaNamesOfDivisionBn,
+  isUpazila, isUpazilabn,
+  getUpazila, getUpazilabn,
+  getDistrictOfUpazila, getDistrictOfUpazilabn,
+  upazilaData,
+} from "bd-geo-address"
+
+allUpazila()                 // → all 595 upazila names
+
+upazilasOf("Tangail")
+// → [{ upazila: 'Tangail Sadar', upazilaBn: 'টাঙ্গাইল সদর', district: 'Tangail', ... }, ...]
+
+upazilaNamesOf("Tangail")    // → ['Tangail Sadar', 'Basail', 'Bhuapur', ...]
+upazilaNamesOfBn("টাঙ্গাইল") // → Bangla upazila names for Tangail
+
+upazilasOfDivision("Sylhet") // → all upazilas in Sylhet division
+
+isUpazila("Savar")           // → true
+isUpazila("Gulshan")         // → false  (metropolitan thana)
+isUpazilabn("সাভার")          // → true
+
+getUpazila("Savar")
+// → { upazila: 'Savar', upazilaBn: 'সাভার', district: 'Dhaka', division: 'Dhaka', ... }
+
+// Disambiguate names that appear in multiple divisions:
+getUpazila("Mohammadpur", "Khulna")
+// → { upazila: 'Mohammadpur', district: 'Magura', division: 'Khulna', ... }
+
+getDistrictOfUpazila("Savar")      // → 'Dhaka'
+getDistrictOfUpazilabn("সাভার")    // → 'Dhaka'
+
+upazilaData   // raw Upazila[] constant — all 595 objects
+```
+
+---
+
+### Thana
+
+The 26 metropolitan police thanas across Dhaka (15), Chattogram (6), Khulna (3), and Rajshahi (2).
+
+```ts
+import {
+  allThana, allThanaNames,
+  thanasOf, thanasOfBn,
+  thanaNamesOf, thanaNamesOfBn,
+  isThana, isThanabn,
+  getThana, getThanabn,
+  thanaData,
+} from "bd-geo-address"
+
+allThana()                  // → all 26 Thana objects
+allThanaNames()             // → ['Adabor', 'Badda', 'Banani', ..., 'Matihar']
+
+thanasOf("Dhaka")           // → 15 Dhaka thana objects
+thanaNamesOf("Dhaka")       // → ['Adabor', 'Badda', 'Banani', ...]
+thanaNamesOfBn("ঢাকা")      // → Bangla thana names
+
+// isThana without district = true if it is a thana in any city
+isThana("Gulshan")               // → true
+isThana("Kotwali", "Dhaka")      // → true   (disambiguate)
+isThana("Kotwali", "Chattogram") // → true
+isThanabn("গুলশান")              // → true
+
+getThana("Gulshan")
+// → { thana: 'Gulshan', thanaBn: 'গুলশান', district: 'Dhaka', division: 'Dhaka', type: 'thana' }
+
+getThana("Kotwali", "Chattogram")
+// → { thana: 'Kotwali', district: 'Chattogram', ... }
+
+thanaData   // raw Thana[] constant — all 26 objects
+```
+
+| City       | Thanas |
+|------------|--------|
+| Dhaka      | 15     |
+| Chattogram | 6      |
+| Khulna     | 3      |
+| Rajshahi   | 2      |
+
+---
+
+### Search
+
+```ts
+import { searchLocations } from "bd-geo-address"
+
+searchLocations("pur")
+// → matches any division, district, upazila, or thana containing "pur"
+// → [{ name: 'Rangpur', type: 'division' }, { name: 'Mirpur', type: 'thana', district: 'Dhaka' }, ...]
+
+searchLocations("সিলেট")
+// → Bangla search works the same way
+```
+
+---
+
+### FHIR Code Resolution
+
+```ts
+import { resolveCode, resolveCodes } from "bd-geo-address"
+
+resolveCode("30262530")
+// {
+//   fhirCode: '30262530',
+//   thana:    { code: '30262530', name: 'Kafrul', level: 'thana', ... },
+//   city_corp:{ name: 'Dhaka North City Corporation', ... },
+//   district: { name: 'Dhaka', ... },
+//   division: { name: 'Dhaka', ... },
+//   formatted: {
+//     en:      'Kafrul, Dhaka North City Corporation, Dhaka, Dhaka Division',
+//     bn:      'কাফরুল, ঢাকা উত্তর সিটি কর্পোরেশন, ঢাকা, ঢাকা বিভাগ',
+//     short:   'Kafrul, Dhaka',
+//     shortBn: 'কাফরুল, ঢাকা'
+//   },
+//   postal: { postalCode: '1216', postOfficeName: 'Kafrul', ... }
+// }
+
+resolveCodes(["30262530", "10040009", "INVALID"])
+// → [BDAddress, BDAddress, null]
+```
+
+---
+
+### Address Formatting
+
+```ts
+import { toAddressString, toShortAddress, toCustomAddress } from "bd-geo-address"
+
+toAddressString("30262530")
+// → 'Kafrul, Dhaka North City Corporation, Dhaka, Dhaka Division'
+
+toAddressString("30262530", "bn")
+// → 'কাফরুল, ঢাকা উত্তর সিটি কর্পোরেশন, ঢাকা, ঢাকা বিভাগ'
+
+toShortAddress("30262530")       // → 'Kafrul, Dhaka'
+toShortAddress("30262530", "bn") // → 'কাফরুল, ঢাকা'
+
+toCustomAddress("30262530", ["thana", "district", "division"])
+// → 'Kafrul, Dhaka, Dhaka Division'
+
+toCustomAddress("30262530", ["thana", "district"], "bn")
+// → 'কাফরুল, ঢাকা'
+```
+
+---
+
+### Lookup by FHIR Code
+
+```ts
+import { getByCode, findByName, findByNameBn, search, getAllByLevel } from "bd-geo-address"
+
+getByCode("30")               // → { code: '30', name: 'Dhaka', level: 'division', ... }
+getByCode("INVALID")          // → null
+
+findByName("Dhaka")           // → [division, district, ...]
+findByName("Dhaka", "district") // → [{ name: 'Dhaka', level: 'district', ... }]
+findByNameBn("ঢাকা")          // → same but by Bangla name
+
+search("Dhaka")               // → English first, then Bangla fallback
+
+getAllByLevel("division")      // → all 8 division BDLocation objects
+getAllByLevel("district")      // → all 64 district BDLocation objects
+getAllByLevel("upazila")       // → all upazila BDLocation objects
+```
+
+---
+
+### Hierarchy
+
+```ts
+import { getParent, getChildren, getAllDescendants, getHierarchy } from "bd-geo-address"
+
+getParent("1004")              // → { code: '10', name: 'Barishal', level: 'division', ... }
+getParent("10")                // → null  (divisions have no parent)
+
+getChildren("10")              // → all direct children of Barishal division
+getAllDescendants("10")        // → all locations under Barishal at any depth
+getAllDescendants("10", "district")  // → only districts
+getAllDescendants("10", "upazila")   // → only upazilas
+
+getHierarchy("30262530")
+// → BDAddress without the `formatted` field
+```
+
+---
+
+### Validation
+
+```ts
+import { isValidCode, isValidName, isValidNameBn, isChildOf, getLevel } from "bd-geo-address"
+
+isValidCode("30262530")   // → true
+isValidCode("INVALID")    // → false
+
+isValidName("Dhaka")               // → true
+isValidName("Dhaka", "division")   // → true
+isValidName("Dhaka", "upazila")    // → false
+isValidNameBn("ঢাকা", "division")  // → true
+
+isChildOf("10040009", "10")        // → true  (in Barishal division)
+isChildOf("10040009", "1004")      // → true  (in Barguna district)
+isChildOf("10040009", "30")        // → false (not in Dhaka)
+
+getLevel("10")        // → 'division'
+getLevel("1004")      // → 'district'
+getLevel("10040009")  // → 'upazila'
+getLevel("INVALID")   // → null
+```
+
+---
+
+### Postal Codes
+
+```ts
+import {
+  getByPostalCode, getPostalCode, getPostalCodeBn,
+  getPostalCodesByArea, getFhirCodeFromPostal, resolvePostalCode,
+} from "bd-geo-address"
+
+getByPostalCode("8710")
+// → { postalCode: '8710', postOfficeName: 'Amtali', upazilaName: 'Amtali', districtName: 'Barguna', ... }
+
+getPostalCode("Amtali")          // → '8710'
+getFhirCodeFromPostal("8710")    // → '10040009'  (Amtali upazila FHIR code)
+
+getPostalCodesByArea("Barguna", "district")  // → all postal entries in Barguna district
+getPostalCodesByArea("Barisal", "division")  // → all postal entries in Barisal division
+
+resolvePostalCode("8710")
+// → full BDAddress for Amtali (same as resolveCode('10040009'))
+```
+
+---
+
+### Geolocation
+
+> Coordinate data requires running `npm run build:coords` with HDX shapefiles.
+
+```ts
+import { getCoordinates, getNearestLocation, getLocationsWithinRadius } from "bd-geo-address"
+
+getCoordinates("30")                  // → { lat: 23.8103, lng: 90.4125 }
+getNearestLocation(23.7, 90.4)        // → nearest BDLocation to the point
+getNearestLocation(23.7, 90.4, "upazila")  // → nearest upazila
+getLocationsWithinRadius(23.7, 90.4, 50)   // → all locations within 50 km
+```
+
+---
+
+## TypeScript Types
+
+```ts
+import type {
+  DivisionName,     // enum
+  DistrictName,     // string literal union of all 64 districts
+  LocationLevel,    // 'division' | 'district' | 'city_corp' | 'municipality' | 'upazila' | 'thana' | 'union' | 'paurasava'
+  Upazila,
+  Thana,
+  SearchResult,
+  BDLocation,
+  BDAddress,
+  BDPostalEntry,
+} from "bd-geo-address"
+```
+
+**`BDAddress`** — resolved FHIR geocode result:
+```ts
+interface BDAddress {
+  fhirCode:      string
+  division:      BDLocation
+  district:      BDLocation
+  city_corp?:    BDLocation
+  municipality?: BDLocation
+  upazila?:      BDLocation
+  thana?:        BDLocation
+  union?:        BDLocation
+  paurasava?:    BDLocation
+  formatted: { en: string; bn: string; short: string; shortBn: string }
+  coordinates?: { lat: number; lng: number }
+  postal?:      { postalCode: string; postOfficeName: string; postOfficeNameBn: string }
+}
+```
+
+**`DivisionName`** enum — use for IDE autocomplete:
+```ts
+import { DivisionName } from "bd-geo-address"
+
+DivisionName.Dhaka      // → 'Dhaka'
+DivisionName.Chattogram // → 'Chattogram'
+// Dhaka, Chattogram, Mymensingh, Khulna, Rajshahi, Rangpur, Sylhet, Barisal
+```
+
+---
+
+## Framework Examples
+
+### React — Cascade Location Picker
+
+```tsx
+import { useState } from "react"
+import { allDivision, districtsOf, upazilasOf } from "bd-geo-address"
+
+export function LocationPicker({ onChange }) {
+  const [division, setDivision] = useState("")
+  const [district, setDistrict] = useState("")
+
+  const districts = division ? districtsOf(division) : []
+  const upazilas  = district ? upazilasOf(district) : []
+
+  return (
+    <div>
+      <select onChange={e => { setDivision(e.target.value); setDistrict("") }}>
+        <option value="">Division</option>
+        {allDivision().map(d => <option key={d} value={d}>{d}</option>)}
+      </select>
+      <select onChange={e => setDistrict(e.target.value)} disabled={!division}>
+        <option value="">District</option>
+        {districts.map(d => <option key={d} value={d}>{d}</option>)}
+      </select>
+      <select onChange={e => onChange(e.target.value)} disabled={!district}>
+        <option value="">Upazila</option>
+        {upazilas.map(u => (
+          <option key={u.upazila} value={u.upazila}>{u.upazilaBn} ({u.upazila})</option>
+        ))}
+      </select>
+    </div>
+  )
+}
+```
+
+### Next.js — Server Component
+
+```tsx
+import { resolveCode } from "bd-geo-address"
+
+export default async function UserPage({ params }) {
+  const user = await fetchUser(params.id)
+  const address = resolveCode(user.locationCode)
+
+  return (
+    <div>
+      <p>{address?.formatted.en}</p>
+      <p>{address?.formatted.bn}</p>
+    </div>
+  )
+}
+```
+
+### Vue 3
+
+```vue
+<template>
+  <select v-model="selectedDivision">
+    <option v-for="d in divisions" :key="d" :value="d">{{ d }}</option>
+  </select>
+  <select v-model="selectedDistrict">
+    <option v-for="d in districts" :key="d" :value="d">{{ d }}</option>
+  </select>
+</template>
+
+<script setup lang="ts">
+import { ref, computed } from "vue"
+import { allDivision, districtsOf } from "bd-geo-address"
+
+const selectedDivision = ref("")
+const divisions = allDivision()
+const districts = computed(() =>
+  selectedDivision.value ? districtsOf(selectedDivision.value) : []
+)
+</script>
+```
+
+### Node.js / Express
+
+```ts
+import express from "express"
+import { isValidCode, resolveCode, upazilasOf } from "bd-geo-address"
+
+const app = express()
+
+app.get("/address/:code", (req, res) => {
+  if (!isValidCode(req.params.code)) return res.status(400).json({ error: "Invalid geocode" })
+  res.json(resolveCode(req.params.code))
+})
+
+app.get("/upazilas/:district", (req, res) => {
+  res.json(upazilasOf(req.params.district))
+})
+```
+
+### NestJS
+
+```ts
+import { Injectable, BadRequestException } from "@nestjs/common"
+import { resolveCode, isValidCode, BDAddress } from "bd-geo-address"
+
+@Injectable()
+export class LocationService {
+  resolve(fhirCode: string): BDAddress {
+    if (!isValidCode(fhirCode)) throw new BadRequestException("Invalid BD FHIR geocode")
+    return resolveCode(fhirCode)!
+  }
+}
+```
+
+---
+
+## Database Dumps
+
+For PHP, Python, Java, Go, Ruby or any non-JS project, database dumps are included in the package.
+
+| File | Format |
+|------|--------|
+| `db/mysql/bangladesh-address.sql` | MySQL 8.0+ |
+| `db/postgresql/bangladesh-address.sql` | PostgreSQL 13+ |
+| `db/sqlite/bangladesh-address.db` | SQLite 3 binary |
+| `db/mongodb/bangladesh-address.json` | MongoDB insertMany-ready |
+
+**Schema:**
+- `divisions` — 8 rows (code, name, name_bn, lat, lng)
+- `districts` — 64 rows (code, name, name_bn, division_code, lat, lng)
+- `locations` — 1519 rows (all other FHIR locations: city corps, upazilas, unions, etc.)
+- `thanas` — 26 metropolitan thanas
+- `postal_codes` — 1343 postal code entries
+
+**MySQL example:**
+```bash
+mysql -u root -p mydb < node_modules/bd-geo-address/db/mysql/bangladesh-address.sql
+```
+
+**PostgreSQL example:**
+```bash
+psql -U postgres mydb < node_modules/bd-geo-address/db/postgresql/bangladesh-address.sql
+```
+
+**SQLite example:**
+```bash
+cp node_modules/bd-geo-address/db/sqlite/bangladesh-address.db ./my-app.db
+```
+
+**MongoDB example:**
+```js
+const data = require("bd-geo-address/db/mongodb/bangladesh-address.json")
+await db.collection("divisions").insertMany(data.divisions)
+await db.collection("locations").insertMany(data.locations)
+```
+
+---
+
+## Data Coverage
+
+| Level | Count |
+|-------|-------|
+| Divisions | 8 |
+| Districts | 64 |
+| City Corporations | 12 |
+| Upazilas | 595 |
+| Metropolitan Thanas | 26 |
+| Unions | 848 |
+| Postal codes | 1343 |
+
+---
+
+## Data Sources & Credits
+
+- **FHIR geocodes** — [DGHS Bangladesh FHIR Server](https://fhir.dghs.gov.bd/core/CodeSystem-bd-geocodes.html)
+- **Postal codes** — [saaiful/postcode-bd](https://github.com/saaiful/postcode-bd)
+- **Coordinates** (optional) — [HDX Bangladesh Admin Boundaries](https://data.humdata.org/dataset/cod-ab-bgd)
+- **Bangla names** — HDX shapefiles + manual curation
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on fixing data, adding tests, or improving the API.
+
+---
+
+## License
+
+[MIT](./LICENSE)