rwanda

A comprehensive TypeScript/JavaScript library for accessing administrative divisions of Rwanda. This package provides type-safe access to provinces, districts, sectors, cells, and villages in Rwanda.

Rwanda is administratively organized into:

• 5 Provinces (including Kigali City)
• 30 Districts
• 416 Sectors
• 2,148 Cells
• 14,837 Villages

Installation

# Using npm
npm install rwanda

# Using yarn
yarn add rwanda

# Using pnpm
pnpm add rwanda

Usage

JavaScript (CommonJS)

const { Provinces, Districts } = require('rwanda');

console.log(Provinces());
// Output: ['East', 'Kigali', 'North', 'South', 'West']

console.log(Districts('kigali'));
// Output: ['Gasabo', 'Kicukiro', 'Nyarugenge']

TypeScript / ES Modules

import { Provinces, Districts, Sectors } from 'rwanda';

// Get all provinces
const provinces: string[] = Provinces();

// Get districts in Kigali
const kigaliDistricts: string[] = Districts('kigali');

// Get sectors in Gasabo district
const gasaboSectors: string[] = Sectors('kigali', 'gasabo');

API Reference

Provinces(): string[]

Returns an array of all provinces in Rwanda.

import { Provinces } from 'rwanda';

const provinces = Provinces();
// Returns: ['East', 'Kigali', 'North', 'South', 'West']

Districts(province?: string): string[] | undefined

• province (optional): Name of the province to filter districts

Returns an array of districts. If a province is provided, returns only districts in that province.

import { Districts } from 'rwanda';

// Get all districts in Rwanda
const allDistricts = Districts();

// Get districts in Kigali
const kigaliDistricts = Districts('kigali');
// Returns: ['Gasabo', 'Kicukiro', 'Nyarugenge']

Sectors(province?: string, district?: string): string[] | undefined

• province (optional): Name of the province
• district (optional): Name of the district to filter sectors

Returns sectors based on the provided filters.

import { Sectors } from 'rwanda';

// Get all sectors in Rwanda
const allSectors = Sectors();

// Get sectors in Gasabo district, Kigali
const gasaboSectors = Sectors('kigali', 'gasabo');

Cells(province?: string, district?: string, sector?: string): string[] | undefined

• province (optional): Name of the province
• district (optional): Name of the district
• sector (optional): Name of the sector to filter cells

Returns cells based on the provided filters.

Villages(province?: string, district?: string, sector?: string, cell?: string): string[] | undefined

• province (optional): Name of the province
• district (optional): Name of the district
• sector (optional): Name of the sector
• cell (optional): Name of the cell to filter villages

Returns villages based on the provided filters.

Type Safety

The package includes TypeScript type definitions out of the box. All functions are properly typed:

// TypeScript will infer the return type as string[]
const districts: string[] = Districts('kigali');

// TypeScript will show an error for invalid province names
const invalid = Districts('invalid'); // TypeScript error

Case Insensitivity

All input parameters are case-insensitive:

// All these are equivalent
Districts('kigali');
Districts('Kigali');
Districts('KIGALI');

Error Handling

When invalid parameters are provided, the functions return undefined:

const result = Districts('Nonexistent Province');
console.log(result); // undefined

yarn add rwanda

Contributors