sl-address 0.1.0

package/README.md

@@ -0,0 +1,91 @@
+# sl-address
+
+TypeScript utilities for exploring Sri Lanka provinces, districts, cities, and postal codes. Ship a single package and unlock lookups, fuzzy search, and readable formatting for any Sri Lankan address workflow.
+
+## Features
+
+- Complete dataset covering every Sri Lankan postal code with its city, district, and province
+- Friendly lookup helpers for provinces, districts, cities, and postal codes
+- JSON-first responses that drop straight into APIs, CLIs, or UIs
+- Fuzzy search, auto-complete, and normalization helpers to tidy user input
+
+## Install
+
+```bash
+npm install sl-address
+```
+
+## Quick Start
+
+```ts
+import postalService, { p } from 'sl-address';
+
+// `p` and the default export reference the same PostalService instance.
+console.log(p.getProvinces());
+console.log(p.getInfoByPostal('10280'));
+console.log(postalService.toReadable('10280')); // "Maharagama, Colombo, Western Province"
+```
+
+CommonJS usage:
+
+```js
+const { p } = require('sl-address');
+
+console.log(p.getDistrictsByProvince('Western Province'));
+```
+
+All methods return JSON-friendly data (arrays, objects, or strings) so they can be serialized or sent over the wire without extra work.
+
+## API Overview
+
+- `getProvinces()` – every province (`"Western Province"`, `"Central Province"`, ...)
+- `getDistricts()` – every district name
+- `getCities()` – every city name
+- `getPostals()` – full dataset of postal records
+- `getDistrictsByProvince(province)` – districts within a province
+- `getCitiesByDistrict(district)` – cities in a district
+- `getCitiesByProvince(province)` – cities in a province
+- `getPostalsByDistrict(district)` – postal records for a district
+- `getPostalsByProvince(province)` – postal records grouped by district
+- `getPostalsByCity(city)` – postal records for a city
+- `getInfoByPostal(code)` – full record for a code
+- `getInfoByCity(city)` – all records matching a city (handles multiple codes)
+- `getDistrictByPostal(code)` / `getProvinceByPostal(code)` / `getCityByPostal(code)` – individual fields
+- `isValidPostal(code)` – boolean existence check
+- `searchCity(query, limit?)` – fuzzy matches with scores
+- `autocompleteCity(prefix, limit?)` – suggestion list for partial input
+- `normalize(input)` – best-guess canonical city name
+- `toReadable(code)` – formatted string `"City, District, Province"`
+
+Inputs ignore case, spacing, and whether `"Province"` is appended (e.g., `"Western"` works).
+
+### Fuzzy helpers
+
+```ts
+p.normalize('maha ragama'); // "Maharagama"
+p.searchCity('galleo');     // close matches with similarity scores
+p.autocompleteCity('kan');  // ["Kandy", "Kananke Bazaar", ...]
+```
+
+## Dataset
+
+The package includes `postal-data.json`, generated from the provided `postalcodes.txt`, covering every Sri Lankan postal code along with its city, district, and province. Need to refresh the dataset? Run:
+
+```bash
+npm run generate:data
+```
+
+## Development
+
+```bash
+npm install
+npm run lint
+npm run build
+```
+
+- `npm run generate:data` – convert `postalcodes.txt` into `src/postal-data.json`
+- `npm run build` – compile TypeScript and copy the dataset to `dist/`
+
+## License
+
+MIT © Sumudu Kulathunga

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+import { CitySearchResult, PostalRecord } from './types';
+export declare class PostalService {
+    private readonly records;
+    private readonly postalIndex;
+    private readonly cityIndex;
+    private readonly districtIndex;
+    private readonly provinceIndex;
+    private readonly cityAliases;
+    private readonly districtAliases;
+    private readonly provinceAliases;
+    constructor(records: PostalRecord[]);
+    getDistricts(): string[];
+    getProvinces(): string[];
+    getCities(): string[];
+    getPostals(): PostalRecord[];
+    getDistrictsByProvince(province: string): string[];
+    getCitiesByDistrict(district: string): string[];
+    getCitiesByProvince(province: string): string[];
+    getPostalsByDistrict(district: string): PostalRecord[];
+    getPostalsByProvince(province: string): Record<string, PostalRecord[]>;
+    getInfoByPostal(code: string | number): PostalRecord | null;
+    getInfoByCity(city: string): PostalRecord[];
+    getDistrictByPostal(code: string | number): string | null;
+    getProvinceByPostal(code: string | number): string | null;
+    getCityByPostal(code: string | number): string | null;
+    isValidPostal(code: string | number): boolean;
+    getPostalsByCity(city: string): PostalRecord[];
+    searchCity(query: string, limit?: number): CitySearchResult[];
+    autocompleteCity(input: string, limit?: number): string[];
+    normalize(input: string): string;
+    toReadable(code: string | number): string | null;
+    private addToIndex;
+    private formatRecord;
+    private lookupProvince;
+    private lookupDistrictRecords;
+    private lookupCityRecords;
+    private bestMatch;
+}
+declare const service: PostalService;
+export declare const p: PostalService;
+export default service;
+export type { PostalRecord, CitySearchResult } from './types';

package/dist/index.js

@@ -0,0 +1,281 @@
+"use strict";
+// This npm package provides a comprehensive service for handling postal codes
+// It includes functionalities for retrieving postal codes, cities, districts, and provinces, as well as searching and autocompleting city names.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.p = exports.PostalService = void 0;
+// Author: Sumudu Kulathunga
+// GitHub: https://github.com/sumudu-k/sl-address
+const postal_data_json_1 = __importDefault(require("./postal-data.json"));
+const utils_1 = require("./utils");
+function sanitizeRecord(record) {
+    return {
+        postalCode: record.postalCode.trim(),
+        city: record.city.trim(),
+        district: record.district.trim(),
+        province: record.province.trim(),
+    };
+}
+function normalizeProvinceKey(value) {
+    return (0, utils_1.normalizeKey)(value.replace(/province$/i, ''));
+}
+function normalizePostalCode(value) {
+    const digits = String(value).replace(/[^0-9]/g, '');
+    if (!digits) {
+        return '';
+    }
+    return digits.padStart(5, '0');
+}
+class PostalService {
+    constructor(records) {
+        this.postalIndex = new Map();
+        this.cityIndex = new Map();
+        this.districtIndex = new Map();
+        this.provinceIndex = new Map();
+        this.cityAliases = new Map();
+        this.districtAliases = new Map();
+        this.provinceAliases = new Map();
+        const sanitized = records.map(sanitizeRecord);
+        sanitized.sort((a, b) => a.postalCode.localeCompare(b.postalCode));
+        this.records = sanitized;
+        for (const record of sanitized) {
+            this.addToIndex(this.postalIndex, record.postalCode, record);
+            const cityKey = (0, utils_1.normalizeKey)(record.city);
+            this.addToIndex(this.cityIndex, cityKey, record);
+            if (!this.cityAliases.has(cityKey)) {
+                this.cityAliases.set(cityKey, record.city);
+            }
+            const districtKey = (0, utils_1.normalizeKey)(record.district);
+            this.addToIndex(this.districtIndex, districtKey, record);
+            if (!this.districtAliases.has(districtKey)) {
+                this.districtAliases.set(districtKey, record.district);
+            }
+            const provinceKey = normalizeProvinceKey(record.province);
+            this.addToIndex(this.provinceIndex, provinceKey, record);
+            if (!this.provinceAliases.has(provinceKey)) {
+                this.provinceAliases.set(provinceKey, record.province);
+            }
+        }
+    }
+    getDistricts() {
+        return Array.from(this.districtAliases.values()).sort();
+    }
+    getProvinces() {
+        const provinces = Array.from(this.provinceAliases.values())
+            .map((province) => (0, utils_1.formatProvinceName)(province));
+        return Array.from(new Set(provinces)).sort();
+    }
+    getCities() {
+        return Array.from(this.cityAliases.values()).sort();
+    }
+    getPostals() {
+        return this.records.map((record) => this.formatRecord(record));
+    }
+    getDistrictsByProvince(province) {
+        var _a;
+        const matched = this.lookupProvince(province);
+        if (!matched) {
+            return [];
+        }
+        const records = (_a = this.provinceIndex.get(matched)) !== null && _a !== void 0 ? _a : [];
+        const districts = new Set(records.map((record) => record.district));
+        return Array.from(districts).sort();
+    }
+    getCitiesByDistrict(district) {
+        const records = this.lookupDistrictRecords(district);
+        const cities = new Set(records.map((record) => record.city));
+        return Array.from(cities).sort();
+    }
+    getCitiesByProvince(province) {
+        var _a;
+        const matched = this.lookupProvince(province);
+        if (!matched) {
+            return [];
+        }
+        const records = (_a = this.provinceIndex.get(matched)) !== null && _a !== void 0 ? _a : [];
+        const cities = new Set(records.map((record) => record.city));
+        return Array.from(cities).sort();
+    }
+    getPostalsByDistrict(district) {
+        const records = this.lookupDistrictRecords(district);
+        return records.map((record) => this.formatRecord(record));
+    }
+    getPostalsByProvince(province) {
+        var _a;
+        const matched = this.lookupProvince(province);
+        if (!matched) {
+            return {};
+        }
+        const records = (_a = this.provinceIndex.get(matched)) !== null && _a !== void 0 ? _a : [];
+        const byDistrict = {};
+        for (const record of records) {
+            if (!byDistrict[record.district]) {
+                byDistrict[record.district] = [];
+            }
+            byDistrict[record.district].push(this.formatRecord(record));
+        }
+        for (const district of Object.keys(byDistrict)) {
+            byDistrict[district].sort((a, b) => a.city.localeCompare(b.city));
+        }
+        return byDistrict;
+    }
+    getInfoByPostal(code) {
+        const key = normalizePostalCode(code);
+        const matches = this.postalIndex.get(key);
+        if (!matches || matches.length === 0) {
+            return null;
+        }
+        return this.formatRecord(matches[0]);
+    }
+    getInfoByCity(city) {
+        const records = this.lookupCityRecords(city);
+        return records.map((record) => this.formatRecord(record));
+    }
+    getDistrictByPostal(code) {
+        const info = this.getInfoByPostal(code);
+        return info ? info.district : null;
+    }
+    getProvinceByPostal(code) {
+        const info = this.getInfoByPostal(code);
+        return info ? info.province : null;
+    }
+    getCityByPostal(code) {
+        const info = this.getInfoByPostal(code);
+        return info ? info.city : null;
+    }
+    isValidPostal(code) {
+        const key = normalizePostalCode(code);
+        return this.postalIndex.has(key);
+    }
+    getPostalsByCity(city) {
+        return this.getInfoByCity(city);
+    }
+    searchCity(query, limit = 10) {
+        const normalizedQuery = (0, utils_1.normalizeKey)(query);
+        if (!normalizedQuery) {
+            return [];
+        }
+        const results = [];
+        for (const [key, records] of this.cityIndex.entries()) {
+            const score = (0, utils_1.getScore)(normalizedQuery, key);
+            if (score <= 0.6) {
+                results.push({
+                    city: records[0].city,
+                    district: records[0].district,
+                    province: (0, utils_1.formatProvinceName)(records[0].province),
+                    postalCodes: records.map((record) => record.postalCode),
+                    score,
+                });
+            }
+        }
+        results.sort((a, b) => a.score - b.score || a.city.localeCompare(b.city));
+        return results.slice(0, limit);
+    }
+    autocompleteCity(input, limit = 10) {
+        const lowerInput = input.trim().toLowerCase();
+        if (!lowerInput) {
+            return [];
+        }
+        const matches = new Set();
+        for (const city of this.cityAliases.values()) {
+            if (city.toLowerCase().startsWith(lowerInput)) {
+                matches.add(city);
+            }
+        }
+        if (matches.size < limit) {
+            for (const city of this.cityAliases.values()) {
+                if (city.toLowerCase().includes(lowerInput)) {
+                    matches.add(city);
+                }
+                if (matches.size >= limit) {
+                    break;
+                }
+            }
+        }
+        return Array.from(matches).sort().slice(0, limit);
+    }
+    normalize(input) {
+        var _a;
+        const best = this.bestMatch(input, this.cityAliases);
+        return best ? (_a = this.cityAliases.get(best.key)) !== null && _a !== void 0 ? _a : input.trim() : input.trim();
+    }
+    toReadable(code) {
+        const info = this.getInfoByPostal(code);
+        if (!info) {
+            return null;
+        }
+        return `${info.city}, ${info.district}, ${info.province}`;
+    }
+    addToIndex(map, key, record) {
+        if (!map.has(key)) {
+            map.set(key, []);
+        }
+        map.get(key).push(record);
+    }
+    formatRecord(record) {
+        return {
+            postalCode: record.postalCode,
+            city: record.city,
+            district: record.district,
+            province: (0, utils_1.formatProvinceName)(record.province),
+        };
+    }
+    lookupProvince(province) {
+        const key = normalizeProvinceKey(province);
+        if (this.provinceAliases.has(key)) {
+            return key;
+        }
+        const best = this.bestMatch(key, this.provinceAliases);
+        return best === null || best === void 0 ? void 0 : best.key;
+    }
+    lookupDistrictRecords(district) {
+        var _a;
+        const key = (0, utils_1.normalizeKey)(district);
+        if (this.districtIndex.has(key)) {
+            return this.districtIndex.get(key);
+        }
+        const best = this.bestMatch(key, this.districtAliases);
+        if (best) {
+            return (_a = this.districtIndex.get(best.key)) !== null && _a !== void 0 ? _a : [];
+        }
+        return [];
+    }
+    lookupCityRecords(city) {
+        var _a;
+        const key = (0, utils_1.normalizeKey)(city);
+        if (this.cityIndex.has(key)) {
+            return this.cityIndex.get(key);
+        }
+        const best = this.bestMatch(key, this.cityAliases);
+        if (best) {
+            return (_a = this.cityIndex.get(best.key)) !== null && _a !== void 0 ? _a : [];
+        }
+        return [];
+    }
+    bestMatch(query, aliases) {
+        const normalizedQuery = (0, utils_1.normalizeKey)(query);
+        if (!normalizedQuery) {
+            return undefined;
+        }
+        if (aliases.has(normalizedQuery)) {
+            return { key: normalizedQuery, score: 0 };
+        }
+        let best;
+        for (const key of aliases.keys()) {
+            const score = (0, utils_1.getScore)(normalizedQuery, key);
+            if (score > 0.6) {
+                continue;
+            }
+            if (!best || score < best.score) {
+                best = { key, score };
+            }
+        }
+        return best;
+    }
+}
+exports.PostalService = PostalService;
+const service = new PostalService(postal_data_json_1.default);
+exports.p = service;
+exports.default = service;