📍 locationslk

A typed Sri Lankan locations SDK for provinces and districts.

It provides deterministic lookups, search support (Sinhala / Tamil / English), translation utilities, and validation helpers for Sri Lankan administrative divisions.

🚀 Installation

npm install locationslk
# or
pnpm add locationslk

⚡ Quick Start (TypeScript / ES Modules)

import {
  getProvinceById,
  getDistrictById,
  getDistrictsByProvince,
  searchDistrict,
  searchProvince,
  translateLocation,
  validateAddress,
} from "locationslk";

// Province lookup
const western = getProvinceById("western");

// District lookup
const colombo = getDistrictById("colombo");

// Get districts in a province
const westernDistricts = getDistrictsByProvince("western");

// Search (supports Sinhala / Tamil / English)
const districtMatches = searchDistrict("කො");
const provinceMatches = searchProvince("West");

// Translation
const translated = translateLocation("Colombo", "si");

// Validation
const isValid = validateAddress({
  provinceId: "western",
  districtId: "colombo",
});

📦 CommonJS Usage

const { getDistrictById, searchDistrict } = require("locationslk");

console.log(getDistrictById("colombo"));
console.log(searchDistrict("Amp"));

🎯 Features

• 🇱🇰 Sri Lanka provinces & districts dataset
• 🔎 Fast search (Sinhala / Tamil / English support)
• 🧭 Deterministic ID-based lookups
• 🌐 Translation support
• ✅ Address validation
• ⚡ Lightweight and tree-shakable

🧩 API Reference

Provinces

getProvinces();
getProvinceById(id);
getProvinceByCode(code);

Districts

getDistricts();
getDistrictById(id);
getDistrictByCode(code);
getDistrictsByProvince(provinceId);

Search

searchProvince(query);
searchDistrict(query);

Supports partial matching and multilingual input.

Translation

translateLocation(input, language);

Languages:

type Language = "en" | "si" | "ta";

Validation

isValidProvince(id);
isValidDistrict(id);

validateAddress({
  provinceId,
  districtId,
});

🧪 Development

pnpm install
pnpm build
pnpm test

Watch mode:

pnpm dev

🧪 Testing

Uses Vitest for unit testing.

pnpm test

📁 Use Cases

• 🏠 Sri Lankan address form validation
• 🔍 Autocomplete dropdowns (province/district)
• 🌍 Multi-language location search
• 🗄️ Database seeding with stable location IDs
• 🧾 Backend validation without external APIs

📌 Example: Form Validation Flow

const input = {
  provinceId: "western",
  districtId: "colombo",
};

if (validateAddress(input)) {
  console.log("Valid Sri Lankan address");
} else {
  console.log("Invalid address");
}