geo-sl 1.0.0

package/dist/cities.d.cts

@@ -0,0 +1,89 @@
+import { City, QueryOptions, DistrictCode, ProvinceCode, Language, SearchOptions } from './types.cjs';
+
+declare const CITIES: readonly City[];
+/**
+ * Finds a city or post office by its 5-digit postal code.
+ *
+ * @param postalCode - 5-digit postal code (e.g. '00100' or 100).
+ * @param lang - Target language ('en' | 'si' | 'ta'). Default is 'en'.
+ * @returns Matching City object, or undefined if not found.
+ *
+ * @example
+ * getCityByPostalCode('00100') // => Colombo 1
+ * getCityByPostalCode('20000') // => Kandy
+ */
+declare function getCityByPostalCode(postalCode: string | number, lang?: Language): City | undefined;
+/**
+ * Alias for getCityByPostalCode.
+ *
+ * @see getCityByPostalCode
+ */
+declare function lookupPostalCode(postalCode: string | number, options?: QueryOptions): City | undefined;
+/**
+ * Returns all postal stations or sub-offices that share the specified postal code.
+ *
+ * @param postalCode - 5-digit postal code.
+ * @param options - Query options including language selection.
+ */
+declare function lookupAllByPostalCode(postalCode: string | number, options?: QueryOptions): readonly City[];
+/**
+ * Resolves the 5-digit postal code for a given city name (English, Sinhala, or Tamil).
+ *
+ * @param cityName - Name of the city or town.
+ * @returns 5-digit postal code string, or undefined if not found.
+ *
+ * @example
+ * getPostalCode('Athurugiriya') // => "10150"
+ * getPostalCode('Colombo 1')    // => "00100"
+ * getPostalCode('මහනුවර')      // => "20000"
+ */
+declare function getPostalCode(cityName: string): string | undefined;
+/**
+ * Checks whether a given postal code exists in the official Sri Lanka Post dataset.
+ *
+ * @param postalCode - 5-digit postal code.
+ *
+ * @example
+ * isValidPostalCode('00100') // => true
+ * isValidPostalCode('99999') // => false
+ */
+declare function isValidPostalCode(postalCode: string | number): boolean;
+/**
+ * Returns all cities and post offices within a district.
+ *
+ * @param district - District code (e.g. 'CO') or district name.
+ * @param options - Query options including language selection.
+ *
+ * @example
+ * getCitiesByDistrict('CO')       // => Colombo cities
+ * getCitiesByDistrict('Gampaha')  // => Gampaha cities
+ */
+declare function getCitiesByDistrict(district: DistrictCode | string, options?: QueryOptions): readonly City[];
+/**
+ * Returns all cities and post offices within a province.
+ *
+ * @param province - Province code (e.g. 'WP') or province name.
+ * @param options - Query options including language selection.
+ */
+declare function getCitiesByProvince(province: ProvinceCode | string, options?: QueryOptions): readonly City[];
+/**
+ * Returns cities and post offices, optionally filtered by district.
+ *
+ * @param districtOrOptions - District code/name or query options.
+ * @param options - Query options if district was specified as first argument.
+ */
+declare function getCities(districtOrOptions?: string | QueryOptions, options?: QueryOptions): readonly City[];
+/**
+ * Searches cities, towns, and postal stations across English, Sinhala, and Tamil.
+ * Uses relevance scoring to prioritize exact and prefix matches over district matches.
+ *
+ * @param query - Search term (town name, postal code, or district).
+ * @param options - Search options including limit, language, and district/province filters.
+ *
+ * @example
+ * search('colombo') // => ['Colombo 1', 'Colombo 2', ...]
+ * search('nawala')  // => ['Nawala', 'Nawala-Koswatte', ...]
+ */
+declare function search(query: string, options?: SearchOptions): City[];
+
+export { CITIES, getCities, getCitiesByDistrict, getCitiesByProvince, getCityByPostalCode, getPostalCode, isValidPostalCode, lookupAllByPostalCode, lookupPostalCode, search };

package/dist/cities.d.ts

@@ -0,0 +1,89 @@
+import { City, QueryOptions, DistrictCode, ProvinceCode, Language, SearchOptions } from './types.js';
+
+declare const CITIES: readonly City[];
+/**
+ * Finds a city or post office by its 5-digit postal code.
+ *
+ * @param postalCode - 5-digit postal code (e.g. '00100' or 100).
+ * @param lang - Target language ('en' | 'si' | 'ta'). Default is 'en'.
+ * @returns Matching City object, or undefined if not found.
+ *
+ * @example
+ * getCityByPostalCode('00100') // => Colombo 1
+ * getCityByPostalCode('20000') // => Kandy
+ */
+declare function getCityByPostalCode(postalCode: string | number, lang?: Language): City | undefined;
+/**
+ * Alias for getCityByPostalCode.
+ *
+ * @see getCityByPostalCode
+ */
+declare function lookupPostalCode(postalCode: string | number, options?: QueryOptions): City | undefined;
+/**
+ * Returns all postal stations or sub-offices that share the specified postal code.
+ *
+ * @param postalCode - 5-digit postal code.
+ * @param options - Query options including language selection.
+ */
+declare function lookupAllByPostalCode(postalCode: string | number, options?: QueryOptions): readonly City[];
+/**
+ * Resolves the 5-digit postal code for a given city name (English, Sinhala, or Tamil).
+ *
+ * @param cityName - Name of the city or town.
+ * @returns 5-digit postal code string, or undefined if not found.
+ *
+ * @example
+ * getPostalCode('Athurugiriya') // => "10150"
+ * getPostalCode('Colombo 1')    // => "00100"
+ * getPostalCode('මහනුවර')      // => "20000"
+ */
+declare function getPostalCode(cityName: string): string | undefined;
+/**
+ * Checks whether a given postal code exists in the official Sri Lanka Post dataset.
+ *
+ * @param postalCode - 5-digit postal code.
+ *
+ * @example
+ * isValidPostalCode('00100') // => true
+ * isValidPostalCode('99999') // => false
+ */
+declare function isValidPostalCode(postalCode: string | number): boolean;
+/**
+ * Returns all cities and post offices within a district.
+ *
+ * @param district - District code (e.g. 'CO') or district name.
+ * @param options - Query options including language selection.
+ *
+ * @example
+ * getCitiesByDistrict('CO')       // => Colombo cities
+ * getCitiesByDistrict('Gampaha')  // => Gampaha cities
+ */
+declare function getCitiesByDistrict(district: DistrictCode | string, options?: QueryOptions): readonly City[];
+/**
+ * Returns all cities and post offices within a province.
+ *
+ * @param province - Province code (e.g. 'WP') or province name.
+ * @param options - Query options including language selection.
+ */
+declare function getCitiesByProvince(province: ProvinceCode | string, options?: QueryOptions): readonly City[];
+/**
+ * Returns cities and post offices, optionally filtered by district.
+ *
+ * @param districtOrOptions - District code/name or query options.
+ * @param options - Query options if district was specified as first argument.
+ */
+declare function getCities(districtOrOptions?: string | QueryOptions, options?: QueryOptions): readonly City[];
+/**
+ * Searches cities, towns, and postal stations across English, Sinhala, and Tamil.
+ * Uses relevance scoring to prioritize exact and prefix matches over district matches.
+ *
+ * @param query - Search term (town name, postal code, or district).
+ * @param options - Search options including limit, language, and district/province filters.
+ *
+ * @example
+ * search('colombo') // => ['Colombo 1', 'Colombo 2', ...]
+ * search('nawala')  // => ['Nawala', 'Nawala-Koswatte', ...]
+ */
+declare function search(query: string, options?: SearchOptions): City[];
+
+export { CITIES, getCities, getCitiesByDistrict, getCitiesByProvince, getCityByPostalCode, getPostalCode, isValidPostalCode, lookupAllByPostalCode, lookupPostalCode, search };