Sri Lankan Provinces & Districts 🇱🇰

A modern TypeScript package providing data for all provinces and districts in Sri Lanka.

📋 Table of Contents

• Features
• Installation
• Usage
  • CommonJS (Legacy API)
  • TypeScript / ES Modules
• API Reference
  • Original API
  • TypeScript API
• Framework Examples
  • Node.js
  • React
  • Next.js
  • Nest.js
• Contributing
• License
• Support
• Author

✨ Features

• TypeScript First: Complete type definitions for enhanced developer experience
• Dual Package Format: Both ES Modules and CommonJS support for any project
• Framework Agnostic: Works with Node.js, React, Next.js, Nest.js, and more
• Complete Data: All 9 provinces and 25 districts of Sri Lanka with metadata
• Developer Friendly: Case-insensitive lookups, helpful error handling
• Zero Dependencies: Lightweight and clean implementation
• Backward Compatible: All v1.x API functions still work

📦 Installation

# Using npm
npm install srilankan-provinces-districts

🚀 Usage

CommonJS (Legacy API)

// CommonJS require syntax
const provinceDistricts = require('srilankan-provinces-districts');

// Get all province names as an array
const provinces = provinceDistricts.getProvinces();
console.log(provinces);

## Output
["Western", "Central", "Southern", "Northern", "Eastern", ...]

// Get district names in a province
const westernDistricts = provinceDistricts.getDistricts("Western");
console.log(westernDistricts);

## Output
["Colombo", "Gampaha", "Kalutara"]

TypeScript / ES Modules

// ES Modules import syntax
import { 
  // Types
  Province, 
  District,
  
  // Functions - Legacy API
  getProvinces, 
  getDistricts,
  
  // Functions - New TypeScript API
  getProvince,
  getAllProvinces, 
  getAllDistricts, 
  getDistrictsByProvince 
} from 'srilankan-provinces-districts';

// Get all provinces with detailed data
const provinces: Province[] = getAllProvinces();
console.log(provinces);

## Output 
[
  { id: "western", name: "Western", code: "WP" },
  { id: "central", name: "Central", code: "CP" },
  ...
]


// Get a specific province by name (case-insensitive)
const western: Province | undefined = getProvince('Western');
console.log(western);

### Output
{
  id: "western",
  name: "Western",
  code: "WP"
}

// Get districts in Western province with detailed data
const westernDistricts: District[] = getDistrictsByProvince('Western');
console.log(westernDistricts);

## Output
[
  { id: "colombo", provinceId: "western", name: "Colombo", code: "CMB" },
  { id: "gampaha", provinceId: "western", name: "Gampaha", code: "GMP" },
  { id: "kalutara", provinceId: "western", name: "Kalutara", code: "KLT" }
]

📚 API Reference

Original API

getProvinces()-Returns an array of all province names in Sri Lanka

const provinces = getProvinces();

## Output
// ["Western", "Central", "Southern", "Northern", "Eastern", ...]

getDistricts(provinceName)-Returns an array of all district names in a specific province

const districts = getDistricts("Western");

## Output
// ["Colombo", "Gampaha", "Kalutara"]

TypeScript API

getProvince(nameOrId)-Returns a province by name or ID (case-insensitive)

const province = getProvince("Western"); // Also works with "western" or "WESTERN"

## Output
// { id: "western", name: "Western", code: "WP" }

getAllProvinces()-Returns an array of all provinces with full data

const provinces = getAllProvinces();

## Output
// [{ id: "western", name: "Western", code: "WP" }, ...]

getAllDistricts()-Returns an array of all districts with full data

const districts = getAllDistricts();

##Output
// [{ id: "colombo", provinceId: "western", name: "Colombo", code: "CMB" }, ...]

getDistrictsByProvince(provinceNameOrId)-Returns an array of districts in a specific province

const westernDistricts = getDistrictsByProvince("Western");

## Output
[
   { id: "colombo", provinceId: "western", name: "Colombo", code: "CMB" },
   { id: "gampaha", provinceId: "western", name: "Gampaha", code: "GMP" },
   { id: "kalutara", provinceId: "western", name: "Kalutara", code: "KLT" }
]

🖥️ Framework Examples

• NodeJS Example
• ReactJS Example
• NextJS Example
• NestJS Example

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

• Fork the repository
• Create your feature branch (git checkout -b feature/amazing-feature)
• Commit your changes (git commit -m 'Add some amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Support

💻 Author

Made with ❤️ & ☕ by Dinush Chathurya