JSPM

sl-address

0.1.0
    • ESM via JSPM
    • ES Module Entrypoint
    • Export Map
    • Keywords
    • License
    • Repository URL
    • TypeScript Types
    • README
    • Created
    • Published
    • Downloads 99
    • Score
      100M100P100Q74562F
    • License MIT

    A comprehensive Sri Lankan postal code service package. Includes lookup for provinces, districts, cities, and postal codes, as well as searching and autocompleting city names.

    Package Exports

    • sl-address
    • sl-address/dist/index.js

    This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (sl-address) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

    Readme

    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

    npm install sl-address

    Quick Start

    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:

    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

    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:

    npm run generate:data

    Development

    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