rwanda-geo-data 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SHUMBUSHO Irumva
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# rwanda-locations
+
+Typed, zero-dependency data for Rwanda's administrative hierarchy —
+**Province → District → Sector → Cell → Village** — with a fast, indexed
+query API.
+
+## Why this structure
+
+The data is stored as five flat, normalized arrays (one per level), each
+row carrying an explicit foreign key to its parent (e.g. a `District` has
+a `provinceId`). This is deliberately **not** mirrored as nested
+folders/files per region — at full depth (5 provinces, 30 districts, 416
+sectors, ~2,148 cells, ~14,800+ villages) a one-file-per-region layout
+would mean tens of thousands of files, which hurts install size, git
+performance, and editor responsiveness for no real benefit, since the
+data itself doesn't change per query call.
+
+Lookups are backed by `Map`-based indices built once on first use, so
+`getVillages(cellId)` is O(1) + result size, not a full-array `.filter()`
+every call.
+
+## Installation
+
+```bash
+npm install rwanda-locations
+```
+
+## Usage
+
+```ts
+import {
+  getProvinces,
+  getDistricts,
+  getSectors,
+  getCells,
+  getVillages,
+  getLocationPath,
+  findProvinceByName,
+} from "rwanda-locations";
+
+getProvinces();
+// [{ id: 5, name: "EAST" }, ...]
+
+getDistricts(5);
+// all districts where provinceId === 5
+
+findProvinceByName("east");
+// case-insensitive match -> { id: 5, name: "EAST" }
+
+getLocationPath(501010101);
+// { village, cell, sector, district, province } - full chain in one call
+```
+
+### API
+
+| Function | Description |
+|---|---|
+| `getProvinces()` | All provinces |
+| `getProvinceById(id)` | Single province or `undefined` |
+| `findProvinceByName(name)` | Case-insensitive name match |
+| `getDistricts(provinceId?)` | All districts, or filtered by province |
+| `getDistrictById(id)` | Single district or `undefined` |
+| `findDistrictByName(name, provinceId?)` | Case-insensitive, optionally scoped |
+| `getSectors(districtId?)` | All sectors, or filtered by district |
+| `getSectorById(id)` | Single sector or `undefined` |
+| `findSectorByName(name, districtId?)` | Case-insensitive, optionally scoped |
+| `getCells(sectorId?)` | All cells, or filtered by sector |
+| `getCellById(id)` | Single cell or `undefined` |
+| `findCellByName(name, sectorId?)` | Case-insensitive, optionally scoped |
+| `getVillages(cellId?)` | All villages, or filtered by cell |
+| `getVillageById(id)` | Single village or `undefined` |
+| `findVillageByName(name, cellId?)` | Case-insensitive, optionally scoped |
+| `getLocationPath(villageId)` | Full resolved chain up to province |
+
+## Populating the data
+
+This repo ships with **empty placeholder data files**. To populate them
+from a raw source JSON (shape: nested `Province[]` with `districts` ->
+`sectors` -> `cells` -> `villages`, each child carrying a `*_id` foreign
+key to its parent):
+
+```bash
+npm run generate:data -- path/to/raw-source.json
+```
+
+This flattens the nested JSON into `src/data/{provinces,districts,sectors,cells,villages}.ts`,
+and throws if it finds duplicate ids or a child whose FK doesn't resolve
+to a real parent — catch those before they ship, not after.
+
+## Scripts
+
+```bash
+npm run build         # bundle to dist/ (ESM + CJS + .d.ts) via tsup
+npm run test          # run the test suite once
+npm run test:watch    # watch mode
+npm run lint          # check formatting/lint rules (biome)
+npm run lint:fix      # auto-fix
+npm run generate:data -- <path>   # regenerate src/data/*.ts from raw JSON
+```
+
+## Testing notes
+
+`test/data-integrity.test.ts` validates the **data itself** — uniqueness
+of ids per level, and that every child's foreign key resolves to a real
+parent. Keep this in CI: it's what catches a bad future data refresh
+(duplicate ids, orphaned records) before it ships to consumers.
+
+## License
+
+MIT