bd-geo-address 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,667 @@
+/** All 8 administrative divisions of Bangladesh */
+declare enum DivisionName {
+    Dhaka = "Dhaka",
+    Chattogram = "Chattogram",
+    Mymensingh = "Mymensingh",
+    Khulna = "Khulna",
+    Rajshahi = "Rajshahi",
+    Rangpur = "Rangpur",
+    Sylhet = "Sylhet",
+    Barisal = "Barisal"
+}
+/** Union type of all 64 district names */
+type DistrictName = "Dhaka" | "Faridpur" | "Gazipur" | "Gopalganj" | "Kishoreganj" | "Madaripur" | "Manikganj" | "Munshiganj" | "Narayanganj" | "Narsingdi" | "Rajbari" | "Shariatpur" | "Tangail" | "Bandarban" | "Brahmanbaria" | "Chandpur" | "Chattogram" | "Cox's Bazar" | "Cumilla" | "Feni" | "Khagrachhari" | "Lakshmipur" | "Noakhali" | "Rangamati" | "Jamalpur" | "Mymensingh" | "Netrokona" | "Sherpur" | "Bagerhat" | "Chuadanga" | "Jashore" | "Jhenaidah" | "Khulna" | "Kushtia" | "Magura" | "Meherpur" | "Narail" | "Satkhira" | "Bogura" | "Chapainawabganj" | "Joypurhat" | "Naogaon" | "Natore" | "Pabna" | "Rajshahi" | "Sirajganj" | "Dinajpur" | "Gaibandha" | "Kurigram" | "Lalmonirhat" | "Nilphamari" | "Panchagarh" | "Rangpur" | "Thakurgaon" | "Habiganj" | "Moulvibazar" | "Sunamganj" | "Sylhet" | "Barguna" | "Barisal" | "Bhola" | "Jhalokati" | "Patuakhali" | "Pirojpur";
+/** Administrative level of a location */
+type LocationLevel = "division" | "district" | "city_corp" | "municipality" | "upazila" | "thana" | "union" | "paurasava";
+/** An upazila (sub-district) with its parent hierarchy */
+interface Upazila {
+    upazila: string;
+    upazilaBn: string;
+    district: string;
+    districtBn: string;
+    division: string;
+    divisionBn: string;
+}
+/** A metropolitan police thana */
+interface Thana {
+    thana: string;
+    thanaBn: string;
+    district: string;
+    districtBn: string;
+    division: string;
+    divisionBn: string;
+    type: "thana";
+}
+/** Result from cross-level text search */
+interface SearchResult {
+    name: string;
+    nameBn: string;
+    type: "division" | "district" | "upazila" | "thana";
+    division?: string;
+    district?: string;
+}
+/** A location from the FHIR geocode dataset */
+interface BDLocation {
+    code: string;
+    name: string;
+    nameBn: string;
+    level: LocationLevel;
+    parentCode: string | null;
+    postalCode?: string;
+    postOfficeName?: string;
+    lat?: number;
+    lng?: number;
+}
+/** Full hierarchical address resolved from a FHIR geocode */
+interface BDAddress {
+    fhirCode: string;
+    union?: BDLocation;
+    paurasava?: BDLocation;
+    thana?: BDLocation;
+    upazila?: BDLocation;
+    municipality?: BDLocation;
+    city_corp?: BDLocation;
+    district: BDLocation;
+    division: BDLocation;
+    formatted: {
+        en: string;
+        bn: string;
+        short: string;
+        shortBn: string;
+    };
+    coordinates?: {
+        lat: number;
+        lng: number;
+    };
+    postal?: {
+        postalCode: string;
+        postOfficeName: string;
+        postOfficeNameBn: string;
+    };
+}
+/** A postal code entry */
+interface BDPostalEntry {
+    postalCode: string;
+    postOfficeName: string;
+    postOfficeNameBn: string;
+    upazilaName: string;
+    districtName: string;
+    divisionName: string;
+    fhirCode?: string;
+}
+
+/** All upazila objects (595 entries). */
+declare const upazilaData: Upazila[];
+/** All upazila names in English. */
+declare function allUpazila(): string[];
+/** Alias for allUpazila(). */
+declare function allUpazilaNames(): string[];
+/** All upazila names in Bangla. */
+declare function allUpazilaNamesBn(): string[];
+/** All upazila objects for a given district (English name). */
+declare function upazilasOf(district: DistrictName | string): Upazila[];
+/** All upazila objects for a given district (Bangla name). */
+declare function upazilasOfBn(districtBn: string): Upazila[];
+/** All upazila names (strings) for a given district (English). */
+declare function upazilaNamesOf(district: string): string[];
+/** All upazila names (strings) for a given district (Bangla). */
+declare function upazilaNamesOfBn(districtBn: string): string[];
+/** All upazila objects for a given division (English). */
+declare function upazilasOfDivision(division: DivisionName | string): Upazila[];
+/** All upazila objects for a given division (Bangla). */
+declare function upazilasOfDivisionBn(divisionBn: string): Upazila[];
+/** All upazila names (strings) for a given division (English). */
+declare function upazilaNamesOfDivision(division: string): string[];
+/** All upazila names (strings) for a given division (Bangla). */
+declare function upazilaNamesOfDivisionBn(divisionBn: string): string[];
+/** Returns true if the English name is a known upazila (not a metropolitan thana). */
+declare function isUpazila(name: string): boolean;
+/** Returns true if the Bangla name is a known upazila (not a metropolitan thana). */
+declare function isUpazilabn(nameBn: string): boolean;
+/**
+ * Returns the upazila object for a given English name.
+ * Pass an optional division to disambiguate names that appear in multiple divisions.
+ */
+declare function getUpazila(name: string, division?: string): Upazila | null;
+/**
+ * Returns the upazila object for a given Bangla name.
+ * Pass an optional division (Bangla) to disambiguate.
+ */
+declare function getUpazilabn(nameBn: string, divisionBn?: string): Upazila | null;
+/**
+ * Returns the district an upazila belongs to (English).
+ * Pass an optional division to disambiguate.
+ */
+declare function getDistrictOfUpazila(upazila: string, division?: string): string | null;
+/**
+ * Returns the district an upazila belongs to (Bangla input).
+ * Pass an optional division (Bangla) to disambiguate.
+ */
+declare function getDistrictOfUpazilabn(upazilaBn: string, divisionBn?: string): string | null;
+
+/** All 26 metropolitan thana objects. */
+declare const thanaData: Thana[];
+/** All 26 metropolitan thana objects. */
+declare function allThana(): Thana[];
+/** All 26 metropolitan thana names in English. */
+declare function allThanaNames(): string[];
+/** All thana objects for a given district city (English). */
+declare function thanasOf(district: string): Thana[];
+/** All thana objects for a given district city (Bangla). */
+declare function thanasOfBn(districtBn: string): Thana[];
+/** All thana names (strings) for a given district city (English). */
+declare function thanaNamesOf(district: string): string[];
+/** All thana names (strings) for a given district city (Bangla). */
+declare function thanaNamesOfBn(districtBn: string): string[];
+/**
+ * Returns true if the name is a metropolitan thana.
+ * Pass an optional district to disambiguate (e.g. Kotwali exists in Dhaka and Chattogram).
+ */
+declare function isThana(name: string, district?: string): boolean;
+/**
+ * Returns true if the Bangla name is a metropolitan thana.
+ * Pass an optional district (Bangla) to disambiguate.
+ */
+declare function isThanabn(nameBn: string, districtBn?: string): boolean;
+/**
+ * Returns the thana object for a given English name.
+ * Pass an optional district to disambiguate.
+ */
+declare function getThana(name: string, district?: string): Thana | null;
+/**
+ * Returns the thana object for a given Bangla name.
+ * Pass an optional district (Bangla) to disambiguate.
+ */
+declare function getThanabn(nameBn: string, districtBn?: string): Thana | null;
+
+/**
+ * Returns all 8 division names in English.
+ * @returns Array of English division names.
+ * @example
+ * allDivision()
+ * // → ['Dhaka', 'Chattogram', 'Mymensingh', 'Khulna', 'Rajshahi', 'Rangpur', 'Sylhet', 'Barisal']
+ */
+declare function allDivision(): string[];
+/**
+ * Returns all 8 division names in Bangla.
+ * @returns Array of Bangla division names.
+ * @example
+ * allDivisionBn()
+ * // → ['ঢাকা', 'চট্টগ্রাম', 'ময়মনসিংহ', 'খুলনা', 'রাজশাহী', 'রংপুর', 'সিলেট', 'বরিশাল']
+ */
+declare function allDivisionBn(): string[];
+/**
+ * Returns all districts and upazilas belonging to a division.
+ * Accepts both English and Bangla division names.
+ * @param division - Division name (English or Bangla).
+ * @returns Object with `districts` (string[]) and `upazilas` (Upazila[]), or null if not found.
+ * @example
+ * divisionalDataOf('Dhaka')
+ * // → { districts: ['Dhaka', 'Gazipur', ...], upazilas: [{ upazila: 'Savar', ... }, ...] }
+ *
+ * divisionalDataOf(DivisionName.Sylhet)
+ * // → { districts: ['Sylhet', 'Sunamganj', 'Habiganj', 'Moulvibazar'], upazilas: [...] }
+ */
+declare function divisionalDataOf(division: DivisionName | string): {
+    districts: string[];
+    upazilas: Upazila[];
+} | null;
+/**
+ * Returns all districts and upazilas belonging to a division by Bangla name.
+ * @param divisionBn - Division name in Bangla (e.g. `"ঢাকা"`).
+ * @returns Object with `districts` and `upazilas`, or null if not found.
+ * @example
+ * divisionalDataOfBn('ঢাকা')
+ * // → { districts: ['Dhaka', 'Gazipur', ...], upazilas: [...] }
+ */
+declare function divisionalDataOfBn(divisionBn: string): {
+    districts: string[];
+    upazilas: Upazila[];
+} | null;
+/**
+ * Returns true if the name is a valid Bangladesh division.
+ * @param name - Division name to validate (case-insensitive).
+ * @returns `true` if valid, `false` otherwise.
+ * @example
+ * isValidDivision('Dhaka')       // → true
+ * isValidDivision('InvalidName') // → false
+ */
+declare function isValidDivision(name: string): boolean;
+/**
+ * Returns true if the Bangla name is a valid Bangladesh division.
+ * @param nameBn - Division name in Bangla.
+ * @returns `true` if valid, `false` otherwise.
+ * @example
+ * isValidDivisionBn('ঢাকা')  // → true
+ * isValidDivisionBn('অজানা') // → false
+ */
+declare function isValidDivisionBn(nameBn: string): boolean;
+
+/**
+ * Returns all 64 district names in English.
+ * @returns Array of all district names.
+ * @example
+ * allDistricts()
+ * // → ['Dhaka', 'Gazipur', 'Narayanganj', ..., 'Sylhet', "Cox's Bazar"]
+ */
+declare function allDistricts(): string[];
+/**
+ * Returns all 64 district names in Bangla.
+ * @returns Array of Bangla district names.
+ * @example
+ * allDistrictsBn()
+ * // → ['ঢাকা', 'গাজীপুর', 'নারায়ণগঞ্জ', ...]
+ */
+declare function allDistrictsBn(): string[];
+/**
+ * Returns all district names belonging to a division (English division name).
+ * @param division - Division name in English.
+ * @returns Array of district names, or empty array if division not found.
+ * @example
+ * districtsOf('Dhaka')
+ * // → ['Dhaka', 'Gazipur', 'Kishoreganj', 'Manikganj', 'Munshiganj', ...]
+ */
+declare function districtsOf(division: string): string[];
+/**
+ * Returns all district names belonging to a division (Bangla division name).
+ * @param divisionBn - Division name in Bangla.
+ * @returns Array of district names in English.
+ * @example
+ * districtsOfBn('ঢাকা')
+ * // → ['Dhaka', 'Gazipur', 'Kishoreganj', ...]
+ */
+declare function districtsOfBn(divisionBn: string): string[];
+/**
+ * Returns true if the name is a valid Bangladesh district.
+ * @param name - District name to validate (case-insensitive).
+ * @returns `true` if valid, `false` otherwise.
+ * @example
+ * isValidDistrict('Tangail') // → true
+ * isValidDistrict('Savar')   // → false  (Savar is an upazila)
+ */
+declare function isValidDistrict(name: DistrictName | string): boolean;
+/**
+ * Returns true if the Bangla name is a valid Bangladesh district.
+ * @param nameBn - District name in Bangla.
+ * @returns `true` if valid, `false` otherwise.
+ * @example
+ * isValidDistrictBn('টাঙ্গাইল') // → true
+ * isValidDistrictBn('অজানা')    // → false
+ */
+declare function isValidDistrictBn(nameBn: string): boolean;
+/**
+ * Returns the English division name that the district belongs to.
+ * @param district - District name in English.
+ * @returns Division name, or null if district not found.
+ * @example
+ * getDivisionOfDistrict('Tangail')      // → 'Dhaka'
+ * getDivisionOfDistrict("Cox's Bazar")  // → 'Chattogram'
+ * getDivisionOfDistrict('Unknown')      // → null
+ */
+declare function getDivisionOfDistrict(district: string): string | null;
+/**
+ * Returns the English division name for a district given by its Bangla name.
+ * @param districtBn - District name in Bangla.
+ * @returns Division name in English, or null if not found.
+ * @example
+ * getDivisionOfDistrictBn('টাঙ্গাইল') // → 'Dhaka'
+ */
+declare function getDivisionOfDistrictBn(districtBn: string): string | null;
+
+/**
+ * Cross-level text search across divisions, districts, upazilas, and thanas.
+ * Supports partial English or Bangla queries (case-insensitive for English).
+ * @param query - Partial or full name to search for.
+ * @returns Array of matching locations across all levels.
+ * @example
+ * searchLocations('pur')
+ * // → [
+ * //   { name: 'Rangpur', type: 'division' },
+ * //   { name: 'Rangpur', type: 'district', division: 'Rangpur' },
+ * //   { name: 'Mirpur',  type: 'thana',   district: 'Dhaka', division: 'Dhaka' },
+ * //   ...
+ * // ]
+ *
+ * searchLocations('সিলেট')
+ * // → [{ name: 'Sylhet', nameBn: 'সিলেট', type: 'division' }, ...]
+ */
+declare function searchLocations(query: string): SearchResult[];
+
+/**
+ * Resolves a BD FHIR geocode to a full hierarchical {@link BDAddress}.
+ * Requires at minimum a district-level code (4-digit or longer).
+ * @param code - BD FHIR geocode string (e.g. `"30262530"`).
+ * @returns Full address object, or null if the code is unknown or invalid.
+ * @example
+ * resolveCode('30262530')
+ * // {
+ * //   fhirCode: '30262530',
+ * //   thana:    { 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: 'কাফরুল, ঢাকা'
+ * //   }
+ * // }
+ *
+ * resolveCode('INVALID') // → null
+ */
+declare function resolveCode(code: string): BDAddress | null;
+/**
+ * Resolves multiple BD FHIR geocodes at once.
+ * Null is returned for each code that is not found.
+ * @param codes - Array of FHIR geocode strings.
+ * @returns Array of resolved addresses (parallel to input; null for unknown codes).
+ * @example
+ * resolveCodes(['30262530', '10040009', 'INVALID'])
+ * // → [BDAddress, BDAddress, null]
+ */
+declare function resolveCodes(codes: string[]): (BDAddress | null)[];
+
+/**
+ * Returns a full formatted address string for a FHIR geocode.
+ * @param code - BD FHIR geocode string.
+ * @param lang - Language for the output: `"en"` (default) or `"bn"`.
+ * @returns Formatted address string, or null if the code is not found.
+ * @example
+ * toAddressString('30262530')
+ * // → 'Kafrul, Dhaka North City Corporation, Dhaka, Dhaka Division'
+ *
+ * toAddressString('30262530', 'bn')
+ * // → 'কাফরুল, ঢাকা উত্তর সিটি কর্পোরেশন, ঢাকা, ঢাকা বিভাগ'
+ */
+declare function toAddressString(code: string, lang?: "en" | "bn"): string | null;
+/**
+ * Returns a short address (lowest-level name + district) for a FHIR geocode.
+ * @param code - BD FHIR geocode string.
+ * @param lang - Language for the output: `"en"` (default) or `"bn"`.
+ * @returns Short address string, or null if the code is not found.
+ * @example
+ * toShortAddress('30262530')       // → 'Kafrul, Dhaka'
+ * toShortAddress('30262530', 'bn') // → 'কাফরুল, ঢাকা'
+ */
+declare function toShortAddress(code: string, lang?: "en" | "bn"): string | null;
+/**
+ * Returns a custom address using only the specified administrative levels,
+ * rendered in the order given. Levels absent from the resolved address are skipped.
+ * @param code - BD FHIR geocode string.
+ * @param levels - Ordered list of {@link LocationLevel} values to include.
+ * @param lang - Language for the output: `"en"` (default) or `"bn"`.
+ * @returns Comma-joined address string, or null if the code is not found or no levels match.
+ * @example
+ * toCustomAddress('30262530', ['thana', 'district', 'division'])
+ * // → 'Kafrul, Dhaka, Dhaka Division'
+ *
+ * toCustomAddress('30262530', ['thana', 'district'], 'bn')
+ * // → 'কাফরুল, ঢাকা'
+ */
+declare function toCustomAddress(code: string, levels: LocationLevel[], lang?: "en" | "bn"): string | null;
+
+/**
+ * Returns a single location by its FHIR code, or null if not found.
+ * @param code - BD FHIR geocode string (whitespace is trimmed).
+ * @returns The matching {@link BDLocation}, or null.
+ * @example
+ * getByCode('30')       // → { code: '30', name: 'Dhaka', level: 'division', ... }
+ * getByCode('INVALID')  // → null
+ */
+declare function getByCode(code: string): BDLocation | null;
+/**
+ * Returns all locations matching an English name, optionally filtered by level.
+ * Case-insensitive and whitespace-trimmed.
+ * @param name - English name to look up.
+ * @param level - Optional {@link LocationLevel} to filter results.
+ * @returns Array of matching locations (empty if none found).
+ * @example
+ * findByName('Dhaka')              // → [division, district, ...]
+ * findByName('Dhaka', 'division')  // → [{ name: 'Dhaka', level: 'division', ... }]
+ * findByName('unknown')            // → []
+ */
+declare function findByName(name: string, level?: LocationLevel): BDLocation[];
+/**
+ * Returns all locations matching a Bangla name, optionally filtered by level.
+ * @param nameBn - Bangla name to look up.
+ * @param level - Optional {@link LocationLevel} to filter results.
+ * @returns Array of matching locations (empty if none found).
+ * @example
+ * findByNameBn('ঢাকা')              // → [division, district, ...]
+ * findByNameBn('ঢাকা', 'division')  // → [{ name: 'Dhaka', level: 'division', ... }]
+ */
+declare function findByNameBn(nameBn: string, level?: LocationLevel): BDLocation[];
+/**
+ * Searches by English name first; if no results, searches by Bangla name.
+ * @param query - English or Bangla name.
+ * @param level - Optional {@link LocationLevel} to filter results.
+ * @returns Array of matching locations.
+ * @example
+ * search('Dhaka')   // → English matches
+ * search('ঢাকা')    // → Bangla matches
+ */
+declare function search(query: string, level?: LocationLevel): BDLocation[];
+/**
+ * Returns all locations at a given administrative level.
+ * @param level - The {@link LocationLevel} to retrieve.
+ * @returns Array of all locations at that level.
+ * @example
+ * getAllByLevel('division')  // → 8 division BDLocation objects
+ * getAllByLevel('district')  // → 64 district BDLocation objects
+ */
+declare function getAllByLevel(level: LocationLevel): BDLocation[];
+
+/**
+ * Returns the immediate parent of a location in the FHIR hierarchy.
+ * @param code - BD FHIR geocode string.
+ * @returns The parent {@link BDLocation}, or null if the code is a root (division) or not found.
+ * @example
+ * getParent('1004')  // → { code: '10', name: 'Barishal', level: 'division', ... }
+ * getParent('10')    // → null  (divisions have no parent)
+ */
+declare function getParent(code: string): BDLocation | null;
+/**
+ * Returns all direct children of a location in the FHIR hierarchy.
+ * @param code - BD FHIR geocode string.
+ * @returns Array of child {@link BDLocation} objects, or empty array if none / not found.
+ * @example
+ * getChildren('10')    // → all 6-digit locations under Barishal division
+ * getChildren('INVALID') // → []
+ */
+declare function getChildren(code: string): BDLocation[];
+/**
+ * Returns all descendants of a location at any depth.
+ * Optionally filters to a specific administrative level.
+ * @param code - BD FHIR geocode string.
+ * @param level - Optional {@link LocationLevel} to filter results.
+ * @returns Array of descendant {@link BDLocation} objects.
+ * @example
+ * getAllDescendants('10')              // → all locations under Barishal division
+ * getAllDescendants('10', 'district')  // → only districts under Barishal
+ * getAllDescendants('10', 'upazila')   // → only upazilas under Barishal
+ */
+declare function getAllDescendants(code: string, level?: LocationLevel): BDLocation[];
+/**
+ * Returns the full hierarchy for a FHIR code without the formatted strings.
+ * Useful for storing structured data without the pre-computed string fields.
+ * @param code - BD FHIR geocode string.
+ * @returns A {@link BDAddress} without the `formatted` field, or null if not found.
+ * @example
+ * getHierarchy('30262530')
+ * // → { fhirCode: '30262530', thana: {...}, district: {...}, division: {...}, ... }
+ * // (no `formatted` field)
+ */
+declare function getHierarchy(code: string): Omit<BDAddress, "formatted"> | null;
+
+/**
+ * Returns true if the FHIR code exists in the dataset.
+ * @param code - BD FHIR geocode string (whitespace is trimmed).
+ * @returns `true` if the code is known, `false` otherwise.
+ * @example
+ * isValidCode('30262530') // → true
+ * isValidCode('INVALID')  // → false
+ * isValidCode('')         // → false
+ */
+declare function isValidCode(code: string): boolean;
+/**
+ * Returns true if an English name exists in the dataset.
+ * Optionally checks only at a specific administrative level.
+ * @param name - English name to check (case-insensitive).
+ * @param level - Optional {@link LocationLevel} to restrict the check.
+ * @returns `true` if a match is found, `false` otherwise.
+ * @example
+ * isValidName('Dhaka')              // → true  (exists as division and district)
+ * isValidName('Dhaka', 'division')  // → true
+ * isValidName('Dhaka', 'upazila')   // → false
+ * isValidName('UnknownPlace')       // → false
+ */
+declare function isValidName(name: string, level?: LocationLevel): boolean;
+/**
+ * Returns true if a Bangla name exists in the dataset.
+ * Optionally checks only at a specific administrative level.
+ * @param nameBn - Bangla name to check.
+ * @param level - Optional {@link LocationLevel} to restrict the check.
+ * @returns `true` if a match is found, `false` otherwise.
+ * @example
+ * isValidNameBn('ঢাকা')              // → true
+ * isValidNameBn('ঢাকা', 'division')  // → true
+ * isValidNameBn('ঢাকা', 'upazila')   // → false
+ */
+declare function isValidNameBn(nameBn: string, level?: LocationLevel): boolean;
+/**
+ * Returns true if `childCode` is a descendant of `ancestorCode` at any depth.
+ * @param childCode - The potential child FHIR code.
+ * @param ancestorCode - The potential ancestor FHIR code.
+ * @returns `true` if child is within the ancestor's hierarchy.
+ * @example
+ * isChildOf('10040009', '10')    // → true  (upazila is in Barishal division)
+ * isChildOf('10040009', '1004')  // → true  (upazila is in Barguna district)
+ * isChildOf('10040009', '30')    // → false (not in Dhaka division)
+ * isChildOf('10', '10')          // → false (a code is not a child of itself)
+ */
+declare function isChildOf(childCode: string, ancestorCode: string): boolean;
+/**
+ * Returns the administrative level of a FHIR code, or null if not found.
+ * @param code - BD FHIR geocode string.
+ * @returns The {@link LocationLevel}, or null if the code is unknown.
+ * @example
+ * getLevel('10')       // → 'division'
+ * getLevel('1004')     // → 'district'
+ * getLevel('10040009') // → 'upazila'
+ * getLevel('INVALID')  // → null
+ */
+declare function getLevel(code: string): LocationLevel | null;
+
+/**
+ * Returns a postal entry by postal code, or null if not found.
+ * @param postalCode - Bangladesh postal code string (whitespace is trimmed).
+ * @returns The matching {@link BDPostalEntry}, or null.
+ * @example
+ * getByPostalCode('8710')
+ * // → { postalCode: '8710', postOfficeName: 'Amtali', upazilaName: 'Amtali', ... }
+ *
+ * getByPostalCode('00000') // → null
+ */
+declare function getByPostalCode(postalCode: string): BDPostalEntry | null;
+/**
+ * Returns the postal code for a post office given its English name (exact match, case-insensitive).
+ * @param postOfficeName - English name of the post office.
+ * @returns Postal code string, or null if not found.
+ * @example
+ * getPostalCode('Amtali')  // → '8710'
+ * getPostalCode('unknown') // → null
+ */
+declare function getPostalCode(postOfficeName: string): string | null;
+/**
+ * Returns the postal code for a post office given its Bangla name (exact match).
+ * @param postOfficeNameBn - Bangla name of the post office.
+ * @returns Postal code string, or null if not found.
+ * @example
+ * getPostalCodeBn('আমতলী') // → '8710'  (if Bangla name is set in the dataset)
+ */
+declare function getPostalCodeBn(postOfficeNameBn: string): string | null;
+/**
+ * Returns all postal entries for an area (district or division) by English name.
+ * @param areaName - English name of the district or division.
+ * @param level - Either `"district"` or `"division"`.
+ * @returns Array of matching {@link BDPostalEntry} objects.
+ * @example
+ * getPostalCodesByArea('Barguna', 'district')
+ * // → all postal entries in Barguna district
+ *
+ * getPostalCodesByArea('Barisal', 'division')
+ * // → all postal entries in Barisal division
+ */
+declare function getPostalCodesByArea(areaName: string, level: "district" | "division"): BDPostalEntry[];
+/**
+ * Returns all postal entries for an area by Bangla name.
+ * Note: the current postal dataset does not include Bangla district/division names;
+ * this function always returns an empty array until the data is enriched.
+ * @param areaNameBn - Bangla name of the district or division.
+ * @param level - Either `"district"` or `"division"`.
+ * @returns Array of matching {@link BDPostalEntry} objects (currently always `[]`).
+ */
+declare function getPostalCodesByAreaBn(areaNameBn: string, level: "district" | "division"): BDPostalEntry[];
+/**
+ * Returns the FHIR geocode linked to a postal code, or null if none is linked.
+ * @param postalCode - Bangladesh postal code string.
+ * @returns FHIR geocode string, or null.
+ * @example
+ * getFhirCodeFromPostal('8710') // → '10040009'  (Amtali upazila)
+ * getFhirCodeFromPostal('0000') // → null
+ */
+declare function getFhirCodeFromPostal(postalCode: string): string | null;
+/**
+ * Resolves a postal code all the way to a full {@link BDAddress}.
+ * Internally looks up the linked FHIR code, then calls {@link resolveCode}.
+ * @param postalCode - Bangladesh postal code string.
+ * @returns Full address object, or null if the postal code is not found or has no linked FHIR code.
+ * @example
+ * resolvePostalCode('8710')
+ * // → BDAddress for Amtali, Barguna (same as resolveCode('10040009'))
+ */
+declare function resolvePostalCode(postalCode: string): BDAddress | null;
+
+/**
+ * Returns the centroid coordinates of a location by FHIR code.
+ * Coordinates are available only after running `npm run build:coords`.
+ * @param code - BD FHIR geocode string.
+ * @returns `{ lat, lng }` in decimal degrees, or null if coordinates are not available.
+ * @example
+ * getCoordinates('30')  // → { lat: 23.8103, lng: 90.4125 }  (if shapefiles loaded)
+ * getCoordinates('30')  // → null  (before build:coords is run)
+ */
+declare function getCoordinates(code: string): {
+    lat: number;
+    lng: number;
+} | null;
+/**
+ * Finds the nearest location in the dataset to a given lat/lng point.
+ * Requires coordinate data (`npm run build:coords`).
+ * Optionally filters by administrative level.
+ * @param lat - Latitude in decimal degrees.
+ * @param lng - Longitude in decimal degrees.
+ * @param level - Optional {@link LocationLevel} to restrict the search.
+ * @returns The nearest {@link BDLocation}, or null if no locations have coordinates.
+ * @example
+ * getNearestLocation(23.7, 90.4)              // → nearest location of any level
+ * getNearestLocation(23.7, 90.4, 'division')  // → nearest division centroid
+ */
+declare function getNearestLocation(lat: number, lng: number, level?: LocationLevel): BDLocation | null;
+/**
+ * Returns all locations within a given radius (km) of a lat/lng point.
+ * Requires coordinate data (`npm run build:coords`).
+ * Optionally filters by administrative level.
+ * @param lat - Latitude in decimal degrees.
+ * @param lng - Longitude in decimal degrees.
+ * @param radiusKm - Search radius in kilometres.
+ * @param level - Optional {@link LocationLevel} to restrict the search.
+ * @returns Array of {@link BDLocation} objects within the radius.
+ * @example
+ * getLocationsWithinRadius(23.7, 90.4, 50)              // → all within 50 km
+ * getLocationsWithinRadius(23.7, 90.4, 30, 'upazila')   // → upazilas within 30 km
+ */
+declare function getLocationsWithinRadius(lat: number, lng: number, radiusKm: number, level?: LocationLevel): BDLocation[];
+
+export { type BDAddress, type BDLocation, type BDPostalEntry, type DistrictName, DivisionName, type LocationLevel, type SearchResult, type Thana, type Upazila, allDistricts, allDistrictsBn, allDivision, allDivisionBn, allThana, allThanaNames, allUpazila, allUpazilaNames, allUpazilaNamesBn, districtsOf, districtsOfBn, divisionalDataOf, divisionalDataOfBn, findByName, findByNameBn, getAllByLevel, getAllDescendants, getByCode, getByPostalCode, getChildren, getCoordinates, getDistrictOfUpazila, getDistrictOfUpazilabn, getDivisionOfDistrict, getDivisionOfDistrictBn, getFhirCodeFromPostal, getHierarchy, getLevel, getLocationsWithinRadius, getNearestLocation, getParent, getPostalCode, getPostalCodeBn, getPostalCodesByArea, getPostalCodesByAreaBn, getThana, getThanabn, getUpazila, getUpazilabn, isChildOf, isThana, isThanabn, isUpazila, isUpazilabn, isValidCode, isValidDistrict, isValidDistrictBn, isValidDivision, isValidDivisionBn, isValidName, isValidNameBn, resolveCode, resolveCodes, resolvePostalCode, search, searchLocations, thanaData, thanaNamesOf, thanaNamesOfBn, thanasOf, thanasOfBn, toAddressString, toCustomAddress, toShortAddress, upazilaData, upazilaNamesOf, upazilaNamesOfBn, upazilaNamesOfDivision, upazilaNamesOfDivisionBn, upazilasOf, upazilasOfBn, upazilasOfDivision, upazilasOfDivisionBn };