all-bangladeshi-addresses 1.0.0

package/README.md

@@ -0,0 +1,303 @@
+# all-bangladeshi-addresses
+
+A lightweight TypeScript/JavaScript library that provides **Bangladesh address data** (Division, District, Upazila, Thana) in both **English** and **Bangla**, plus convenient helper functions to query and summarize the data.
+
+---
+
+## Overview
+
+This package bundles curated administrative data of Bangladesh and exposes a set of functions to:
+
+- List divisions, districts, upazilas, and thanas in English and Bangla.
+- Drill down by division or district.
+- Use strongly typed objects in TypeScript.
+
+The library is shipped as compiled JavaScript with type definitions, so consumers can use it directly without access to the original source.
+
+---
+
+## Key Features
+
+- **Bilingual data** – English and Bangla datasets kept in sync.
+- **Administrative hierarchy** – Division → District → Upazila → Thana.
+- **Convenience helpers** – One‑line calls for common lookups.
+- **Aggregate helpers** – Total counts for each administrative level.
+- **Case‑insensitive English lookups** – `"Dhaka"`, `"dhaka"`, `"DHAKA"` all work.
+- **TypeScript support** – Exported interfaces and `.d.ts` files.
+- **Production‑ready build** – Published as compiled code only.
+
+---
+
+## Data Coverage
+
+The package aims to cover:
+
+- **All 8 divisions** of Bangladesh.
+- **All districts** under each division.
+- **All upazilas** under each district.
+- **All thanas (police stations)** mapped to their upazila, district, and division.
+
+Each data row has the shape:
+
+- English: `{ thana, upazilla, district, division }`
+- Bangla: `{ thana, upazilla, district, division }` (names localized to Bangla script)
+
+> Note: Administrative structures can change over time. If you find missing or updated units, please report them via the repository issue tracker or contact the author.
+
+---
+
+## Installation
+
+```bash
+npm install all-bangladeshi-addresses
+
+```
+
+---
+
+## Usage
+
+### Basic example (TypeScript / modern Node)
+
+
+```bash
+import { allDivisionEN, allDivisionBN } from "all-bangladeshi-addresses";
+
+# All English division names
+const divisionsEN = allDivisionEN();
+
+# All Bangla division names
+const divisionsBN = allDivisionBN();
+```
+
+---
+
+## API Reference
+
+Below is a concise reference grouped by language and level.
+
+### English API
+
+#### Divisions
+
+##### `allDivisionEN(): string[]`
+
+Return all **unique English division names**.
+
+```bash
+const divisions = allDivisionEN();
+```
+
+
+##### `divisionalDataENOf(divisionName: string): AddressDataEN[]`
+
+Return all English records (thana rows) under the given **division**.  
+Lookup is **case‑insensitive** on `divisionName`.
+
+```bash
+const dhakaRecords = divisionalDataENOf("dhaka");
+```
+
+
+---
+
+#### Districts
+
+##### `districtENOf(divisionName: string): string[]`
+
+Return all **unique English districts** under the specified **division**.  
+`divisionName` is case‑insensitive.
+
+```bash
+const dhakaDistricts = districtENOf("Dhaka");
+```
+
+
+##### `allDistrictEN(): string[]`
+
+Return all **unique English district names**.
+
+```bash
+const districts = allDistrictEN();
+```
+
+---
+
+#### Upazilas
+
+##### `upazillasENOf(districtName: string): string[]`
+
+Return all **unique English upazila names** under the specified **district**.  
+`districtName` is case‑insensitive.
+
+```bash
+const upazilas = upazillasENOf("Narsingdi");
+```
+
+
+##### `allUpazillaEN(): string[]`
+
+Return all **unique English upazila names**.
+
+```bash
+const allUpazilas = allUpazillaEN();
+
+```
+
+---
+
+#### Thanas
+
+##### `thanasENOf(districtName: string): string[]`
+
+Return all **unique English thana names** under the specified **district**.  
+`districtName` is case‑insensitive.
+
+```bash
+const narsingdiThanas = thanasENOf("Narsingdi");
+```
+
+
+##### `allThanaEN(): string[]`
+
+Return all **unique English thana names**.
+
+```bash
+const allThanas = allThanaEN();
+```
+
+---
+
+### Bangla API
+
+The Bangla API mirrors the English one, but with Bangla strings.
+
+#### Divisions
+
+##### `allDivisionBN(): string[]`
+
+Return all **unique Bangla division names**.
+
+```bash
+const divisionsBn = allDivisionBN();
+```
+
+
+##### `divisionalDataBNOf(divisionName: string): AddressDataBN[]`
+
+Return all Bangla records (thana rows) for the specified Bangla **division** name.
+
+```bash
+const dhakaBnRecords = divisionalDataBNOf("ঢাকা");
+```
+
+
+---
+
+#### Districts
+
+##### `districtBNOf(divisionName: string): string[]`
+
+Return all **unique Bangla districts** under the given Bangla **division**.
+
+```bash
+const dhakaBnDistricts = districtBNOf("ঢাকা");
+```
+
+
+##### `allDistrictBN(): string[]`
+
+Return all **unique Bangla district names**.
+
+```bash
+const allDistrictsBn = allDistrictBN();
+```
+
+
+---
+
+#### Upazilas
+
+##### `upazillasBNOf(districtName: string): string[]`
+
+Return all **unique Bangla upazila names** under the specified Bangla **district**.
+
+```bash
+const narsingdiUpazilasBn = upazillasBNOf("নরসিংদী");
+```
+
+
+##### `allupazillaBN(): string[]`
+
+Return all **unique Bangla upazila names**.
+
+```bash
+const allUpazilasBn = allupazillaBN();
+```
+
+
+---
+
+#### Thanas
+
+##### `thanasBNOf(districtName: string): string[]`
+
+Return all **unique Bangla thana names** under the specified Bangla **district**.
+
+```bash
+const narsingdiThanasBn = thanasBNOf("নরসিংদী");
+```
+
+
+##### `allThanaBN(): string[]`
+
+Return all **unique Bangla thana names**.
+
+```bash
+const allThanasBn = allThanaBN();
+```
+
+
+---
+
+## Types
+
+If you are using TypeScript, you can import the data interfaces:
+
+
+```bash
+import type { AddressDataEN, AddressDataBN } from "all-bangladeshi-addresses";
+
+const enRows: AddressDataEN[] = [];
+const bnRows: AddressDataBN[] = [];
+
+export interface AddressDataEN {
+thana: string;
+upazilla: string;
+district: string;
+division: string;
+}
+
+export interface AddressDataBN {
+thana: string;
+upazilla: string;
+district: string;
+division: string;
+}
+```
+
+
+Each record represents a single thana and its parent upazila, district, and division.
+
+---
+
+## Notes on Case Sensitivity
+
+- All **English** lookup functions (`divisionalDataENOf`, `districtENOf`, `upazillasENOf`, `thanasENOf`) treat the input argument case‑insensitively.
+- **Bangla** parameters should use the correct Bangla spelling; case does not apply in the same way.
+
+---
+
+## Keywords
+
+Bangladesh addresses, BD geo, division, district, upazila, thana, Bangla, English, Bangladeshi addresses, Bangladesh location data