damascus 1.0.0 → 1.2.0

package/README.md

@@ -1,10 +1,13 @@
-# Damascus
+# Syria Regions (focusing on Damascus)
+
+[![Snyk Vulnerabilities](https://img.shields.io/snyk/vulnerabilities/github/hadabo/damascus.svg?style=flat-square)](https://snyk.io/test/github/hadabo/damascus)
 [![Build Status][build-badge]][build]
 [![MIT License][license-badge]][LICENSE]
 [![Semantic release][semantic-release]][semantic]
 [![Damascus package][npm-dm]][damascus]
+[![Coverage Status][coveralls-badge]][coveralls]
 
-Get random districts names of Damascus.
+Get standardized, structured data for the governorates, districts, municipalities, and neighborhoods of Syria, with a **deep-dive into Damascus**. The data is bilingual (Arabic and English) and structured to align with UN OCHA Common Operational Datasets (COD), making it the perfect source of truth for cascading dropdowns and autocompletes in applications like real estate listings, directories, and delivery platforms.
 
 ## Installation
 
@@ -13,23 +16,72 @@ This package is distributed via npm:
 npm install damascus
 ```
 
-## Usage
+## Usage (ES Modules & TypeScript)
+
+Modern projects should import the package via ES Modules. Full TypeScript definitions (`.d.ts`) are included natively for excellent IDE support.
+
+```typescript
+import { search, getAll, getGovernorates, getMunicipalities, getNeighborhoods, SearchResult } from 'damascus';
+
+// 1. Search API (Perfect for Autocomplete)
+const result: SearchResult[] = search('دمشق');
+
+// 2. Get all structured data
+const allData = getAll();
+
+// 3. Get an array of the 14 Syrian governorates
+const governorates = getGovernorates();
+/* 
+[
+  { id: 'dam', name: { en: 'Damascus', ar: 'دمشق' } },
+  { id: 'ale', name: { en: 'Aleppo', ar: 'حلب' } },
+  ...
+]
+*/
+
+// 4. Damascus Specific APIs (Hierarchical)
+const damascusMunicipalities = getMunicipalities('dam'); 
+/*
+[
+  { id: 'dam-municipality-ancient-city-old-city', name: { en: 'Ancient City (Old City)', ar: 'المدينة القديمة' } },
+  ...
+]
+*/
+
+const oldCityNeighborhoods = getNeighborhoods('dam-municipality-ancient-city-old-city');
+/*
+[
+  { id: 'dam-districts-bab-tuma', name: { en: 'Bab Tuma', ar: 'باب توما' } },
+  ...
+]
+*/
+```
+
+### Legacy CommonJS Usage
+If you are still using CommonJS:
 ```javascript
-var damascus = require('damascus');
-var allNames = damascus.all;
-var randomName = damascus.random();
-var threeRandomNames = damascus.random(3);
+const syria = require('damascus');
+const searchResults = syria.search('Bab Tuma'); 
 ```
 
-## Other
-This library was developed by [Abdul-hadi Hawari](https://twitter.com/@hadabo) as a PoC to learn [semantic-release](https://www.npmjs.com/package/semantic-release). 
+## Features
+
+- **Hierarchical Damascus Data**: Perfect for UI components (Select Governorate -> Select Municipality -> Select Neighborhood).
+- **Search Utility**: Built-in search function to easily query the data for autocompletes.
+- **Bilingual**: All items include English (`en`) and Arabic (`ar`) names.
+- **TypeScript Support**: Includes type definitions (`.d.ts`) out of the box for excellent IDE support.
+- **Backward Compatible**: Maintains support for legacy `getDistricts()` API.
 
+## Other
+This library was developed by [Abdul-hadi Hawari](https://twitter.com/@hadabo) as a PoC to learn [semantic-release](https://www.npmjs.com/package/semantic-release), and expanded to be a robust source of truth for Syrian regional data.
 
-[build-badge]: https://img.shields.io/travis/hadabo/damascus.svg?style=flat-square
-[build]: https://travis-ci.org/hadabo/damascus
+[build-badge]: https://img.shields.io/github/actions/workflow/status/hadabo/damascus/ci.yml?style=flat-square
+[build]: https://github.com/hadabo/damascus/actions
 [license-badge]: https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square
 [license]: https://github.com/hadabo/damascus/blob/master/LICENSE
 [semantic-release]: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg?style=flat-square
 [semantic]: https://www.npmjs.com/package/semantic-release
 [npm-dm]: https://img.shields.io/npm/dm/damascus.svg?style=flat-square
-[damascus]: https://www.npmjs.com/package/damascus
+[damascus]: https://www.npmjs.com/package/damascus
+[coveralls]: https://coveralls.io/github/hadabo/damascus?branch=master
+[coveralls-badge]: https://coveralls.io/repos/github/hadabo/damascus/badge.svg?branch=master

package/package.json

@@ -1,50 +1,64 @@
 {
   "name": "damascus",
-  "version": "1.0.0",
-  "description": "Get random districts names of Damascus",
+  "version": "1.2.0",
+  "description": "Hierarchical source of truth for Syrian regional data, focusing on Damascus municipalities and neighborhoods aligned with UN OCHA standards.",
   "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "src"
+  ],
   "scripts": {
     "precommit": "npm test",
     "commit": "git-cz",
-    "lint": "eslint --fix src/*.js",
-    "test": "istanbul cover -x *.test.js _mocha -- -R spec src/index.test.js",
-    "semantic-release": "semantic-release pre && npm publish && semantic-release post"
+    "lint": "eslint src/*.js test/*.js",
+    "lint:fix": "eslint --fix src/*.js test/*.js",
+    "test": "c8 mocha",
+    "coverage": "c8 report --reporter=text-lcov | coveralls",
+    "prepare": "husky"
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/hadabo/damascus.git"
   },
   "keywords": [
-    "random",
     "damascus",
     "syria",
-    "districts"
+    "regions",
+    "governorates",
+    "municipalities",
+    "neighborhoods",
+    "districts",
+    "ocha",
+    "data"
   ],
-  "author": "Abdul-hadi Hawari <hadabo@gmail.com> (http://hadabo.com/)",
+  "author": "Abdulhadi Hawari <hadabo@gmail.com> (http://hadabo.com/)",
   "license": "MIT",
   "bugs": {
     "url": "https://github.com/hadabo/damascus/issues"
   },
   "homepage": "https://github.com/hadabo/damascus#readme",
-  "dependencies": {
-    "unique-random-array": "1.0.0"
-  },
+  "dependencies": {},
   "devDependencies": {
-    "chai": "4.1.2",
-    "commitizen": "2.9.6",
-    "cz-conventional-changelog": "2.0.0",
-    "eslint": "4.9.0",
-    "eslint-config-standard": "10.2.1",
-    "eslint-plugin-import": "2.8.0",
-    "eslint-plugin-node": "5.2.1",
-    "eslint-plugin-promise": "3.6.0",
-    "eslint-plugin-standard": "3.0.1",
-    "husky": "0.14.3",
-    "istanbul": "0.4.5",
-    "mocha": "4.0.1",
-    "semantic-release": "8.2.2"
+    "chai": "^5.1.1",
+    "commitizen": "^4.3.0",
+    "coveralls": "^3.1.1",
+    "cz-conventional-changelog": "^3.3.0",
+    "eslint": "^9.3.0",
+    "globals": "^15.3.0",
+    "husky": "^9.0.11",
+    "mocha": "^10.4.0",
+    "c8": "^9.1.0",
+    "semantic-release": "^23.1.1"
   },
-  "czConfig": {
-    "path": "node_modules/cz-conventional-changelog"
+  "config": {
+    "commitizen": {
+      "path": "node_modules/cz-conventional-changelog"
+    }
   }
 }

package/src/index.d.ts

@@ -0,0 +1,40 @@
+export interface LocalizedName {
+  en: string;
+  ar: string;
+}
+
+export interface Neighborhood {
+  id: string;
+  name: LocalizedName;
+}
+
+export interface Municipality {
+  id: string;
+  name: LocalizedName;
+  neighborhoods?: Neighborhood[];
+}
+
+export interface District {
+  id: string;
+  name: LocalizedName;
+}
+
+export interface Governorate {
+  id: string;
+  name: LocalizedName;
+  municipalities?: Municipality[];
+  districts?: District[];
+}
+
+export interface SearchResult {
+  type: 'governorate' | 'district' | 'municipality' | 'neighborhood';
+  item: Governorate | District | Municipality | Neighborhood;
+  municipalityId?: string;
+}
+
+export function getAll(): Governorate[];
+export function getGovernorates(): Array<{ id: string; name: LocalizedName }>;
+export function getDistricts(governorateId?: string): District[];
+export function getMunicipalities(governorateId?: string): Array<{ id: string; name: LocalizedName }>;
+export function getNeighborhoods(municipalityId: string): Neighborhood[];
+export function search(query: string): SearchResult[];

package/src/index.js

@@ -1,20 +1,105 @@
-const uniqueRandomArray = require('unique-random-array')
-const damascusDistrictsNames = require('./damascus.json')
+import { readFileSync } from 'fs'
+import { fileURLToPath } from 'url'
+import { dirname, join } from 'path'
 
-const getRandomItem = uniqueRandomArray(damascusDistrictsNames)
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const syriaData = JSON.parse(readFileSync(join(__dirname, 'syria.json'), 'utf8'))
 
-function random (number) {
-  if (number === undefined) {
-    return getRandomItem()
+function getAll () {
+  return syriaData
+}
+
+function getGovernorates () {
+  return syriaData.map(gov => ({
+    id: gov.id,
+    name: gov.name
+  }))
+}
+
+function getDistricts (governorateId) {
+  if (governorateId) {
+    const gov = syriaData.find(g => g.id === governorateId)
+    if (!gov) return []
+    // Backward compatibility for Damascus
+    if (gov.municipalities) {
+      return gov.municipalities.reduce((acc, mun) => {
+        acc.push({ id: mun.id, name: mun.name })
+        return acc.concat(mun.neighborhoods)
+      }, [])
+    }
+    return gov.districts || []
   }
-  const randomItems = []
-  for (let i = 0; i < number; i++) {
-    randomItems.push(getRandomItem())
+
+  return syriaData.reduce((allDistricts, gov) => {
+    if (gov.municipalities) {
+      const flatDamascus = gov.municipalities.reduce((acc, mun) => {
+        acc.push({ id: mun.id, name: mun.name })
+        return acc.concat(mun.neighborhoods || [])
+      }, [])
+      return allDistricts.concat(flatDamascus)
+    }
+    return allDistricts.concat(gov.districts || [])
+  }, [])
+}
+
+function getMunicipalities (governorateId = 'dam') {
+  const gov = syriaData.find(g => g.id === governorateId)
+  if (!gov || !gov.municipalities) return []
+  return gov.municipalities.map(m => ({ id: m.id, name: m.name }))
+}
+
+function getNeighborhoods (municipalityId) {
+  for (const gov of syriaData) {
+    if (gov.municipalities) {
+      const mun = gov.municipalities.find(m => m.id === municipalityId)
+      if (mun) return mun.neighborhoods || []
+    }
   }
-  return randomItems
+  return []
+}
+
+function search (query) {
+  if (!query || typeof query !== 'string') return []
+  const q = query.toLowerCase()
+  const results = []
+
+  syriaData.forEach(gov => {
+    if (gov.name.en.toLowerCase().includes(q) || gov.name.ar.includes(q)) {
+      results.push({ type: 'governorate', item: { id: gov.id, name: gov.name } })
+    }
+
+    if (gov.districts) {
+      gov.districts.forEach(dist => {
+        if (dist.name.en.toLowerCase().includes(q) || dist.name.ar.includes(q)) {
+          results.push({ type: 'district', item: dist })
+        }
+      })
+    }
+
+    if (gov.municipalities) {
+      gov.municipalities.forEach(mun => {
+        if (mun.name.en.toLowerCase().includes(q) || mun.name.ar.includes(q)) {
+          results.push({ type: 'municipality', item: { id: mun.id, name: mun.name } })
+        }
+        if (mun.neighborhoods) {
+          mun.neighborhoods.forEach(neigh => {
+            if (neigh.name.en.toLowerCase().includes(q) || neigh.name.ar.includes(q)) {
+              results.push({ type: 'neighborhood', item: neigh, municipalityId: mun.id })
+            }
+          })
+        }
+      })
+    }
+  })
+
+  return results
 }
 
-module.exports = {
-  all: damascusDistrictsNames,
-  random
+export {
+  getAll,
+  getGovernorates,
+  getDistricts,
+  getMunicipalities,
+  getNeighborhoods,
+  search
 }