damascus 1.0.0 → 1.3.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2017 Abdul-hadi Hawari
+Copyright (c) 2017 Abdulhadi Hawari
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,10 +1,17 @@
-# Damascus
+# Damascus (Syrian Regional Data API)
+
+[![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]
+
+The ultimate **environment-agnostic source of truth** for Syrian administrative data. 
+
+This package provides a meticulously standardized, deeply hierarchical dataset covering all of Syria (Governorates ➔ Districts ➔ Municipalities ➔ Neighborhoods/Populated Places). 
 
-Get random districts names of Damascus.
+It is completely aligned with **UN OCHA Common Operational Datasets (COD)**, featuring official P-Codes and geo-spatial coordinates. It's the perfect backbone for cascading dropdowns, map plots, and autocompletes in applications like real estate listings, directories, and delivery platforms.
 
 ## Installation
 
@@ -13,23 +20,78 @@ This package is distributed via npm:
 npm install damascus
 ```
 
-## Usage
-```javascript
-var damascus = require('damascus');
-var allNames = damascus.all;
-var randomName = damascus.random();
-var threeRandomNames = damascus.random(3);
+## Usage (Core API)
+
+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, getDistricts, getMunicipalities, getNeighborhoods } from 'damascus';
+
+// 1. Search API (Perfect for Autocomplete)
+const result = search('دمشق');
+
+// 2. Get the 14 Syrian governorates
+const governorates = getGovernorates();
+/* 
+[
+  { 
+    id: 'dam', 
+    pcode: 'SY01', 
+    coordinates: { lat: 33.5138, lng: 36.2765 },
+    name: { en: 'Damascus', ar: 'دمشق' } 
+  },
+  ...
+]
+*/
+
+// 3. Drill down into the unified hierarchy
+const damascusDistricts = getDistricts('dam'); 
+const municipalities = getMunicipalities('dam-damascus'); 
+const neighborhoods = getNeighborhoods('dam-municipality-ancient-city-old-city');
 ```
 
-## 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). 
+## Usage (React Hooks)
 
+To eliminate boilerplate when building cascading dropdowns, we provide highly-optimized React hooks out of the box!
+
+```typescript
+import { useGovernorates, useDistricts, useMunicipalities } from 'damascus/react';
+import { useState } from 'react';
+
+function LocationSelector() {
+  const [govId, setGovId] = useState('dam');
+  const [distId, setDistId] = useState('dam-damascus');
+
+  const governorates = useGovernorates();
+  const districts = useDistricts(govId); // Automatically reacts to govId changes!
+  const municipalities = useMunicipalities(distId);
+
+  return (
+    // Render your dropdowns...
+  )
+}
+```
+
+## Features
+
+- **Whole of Syria Coverage**: Includes massive generated datasets for all 14 governorates down to populated places.
+- **UN OCHA P-Codes**: Built-in standard `pcode` identifiers for reliable cross-dataset interoperability.
+- **Geo-Spatial Coordinates**: Every level includes precise `{ lat, lng }` coordinates.
+- **React Hooks included**: Exported via `damascus/react` for instant UI integration.
+- **Search Utility**: Built-in search function to easily query the deep data tree.
+- **Bilingual**: All items include English (`en`) and Arabic (`ar`) names.
+- **TypeScript Support**: First-class types mapping the entire hierarchy.
+
+## Other
+This library was developed by [Abdulhadi 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,69 @@
 {
   "name": "damascus",
-  "version": "1.0.0",
-  "description": "Get random districts names of Damascus",
+  "version": "1.3.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",
+    "./react": "./src/react/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",
+    "import-un-data": "node tools/import-un-data.js",
+    "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": {},
+  "peerDependencies": {
+    "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
   },
   "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,52 @@
+export interface LocalizedName {
+  en: string;
+  ar: string;
+}
+
+export interface Coordinates {
+  lat: number;
+  lng: number;
+}
+
+export interface Neighborhood {
+  id: string;
+  pcode?: string;
+  coordinates?: Coordinates;
+  name: LocalizedName;
+}
+
+export interface Municipality {
+  id: string;
+  pcode?: string;
+  coordinates?: Coordinates;
+  name: LocalizedName;
+  neighborhoods?: Neighborhood[];
+}
+
+export interface District {
+  id: string;
+  pcode?: string;
+  coordinates?: Coordinates;
+  name: LocalizedName;
+}
+
+export interface Governorate {
+  id: string;
+  pcode?: string;
+  coordinates?: Coordinates;
+  name: LocalizedName;
+  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,92 @@
-const uniqueRandomArray = require('unique-random-array')
-const damascusDistrictsNames = require('./damascus.json')
+import syriaData from './syria.js'
 
-const getRandomItem = uniqueRandomArray(damascusDistrictsNames)
+function getAll () {
+  return syriaData
+}
+
+function getGovernorates () {
+  return syriaData.map(gov => ({
+    id: gov.id,
+    name: gov.name
+  }))
+}
 
-function random (number) {
-  if (number === undefined) {
-    return getRandomItem()
+function getDistricts (governorateId) {
+  if (governorateId) {
+    const gov = syriaData.find(g => g.id === governorateId)
+    if (!gov) return []
+    return gov.districts || []
   }
-  const randomItems = []
-  for (let i = 0; i < number; i++) {
-    randomItems.push(getRandomItem())
+
+  return syriaData.reduce((allDistricts, gov) => {
+    return allDistricts.concat(gov.districts || [])
+  }, [])
+}
+
+function getMunicipalities (governorateId = 'gov-damascus') {
+  const gov = syriaData.find(g => g.id === governorateId)
+  if (!gov || !gov.districts) return []
+  return gov.districts.reduce((acc, dist) => {
+    return acc.concat(dist.municipalities || [])
+  }, []).map(m => ({ id: m.id, name: m.name, pcode: m.pcode, coordinates: m.coordinates }))
+}
+
+function getNeighborhoods (municipalityId) {
+  for (const gov of syriaData) {
+    if (gov.districts) {
+      for (const dist of gov.districts) {
+        if (dist.municipalities) {
+          const mun = dist.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, pcode: gov.pcode, coordinates: gov.coordinates } })
+    }
+
+    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 (dist.municipalities) {
+          dist.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, pcode: mun.pcode, coordinates: mun.coordinates } })
+            }
+            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
 }

package/src/react/index.d.ts

@@ -0,0 +1,11 @@
+import { Governorate, District, Municipality, Neighborhood } from '../index.js';
+
+export function useGovernorates(): Pick<Governorate, 'id' | 'name' | 'pcode' | 'coordinates'>[];
+export function useDistricts(governorateId?: string): District[];
+export function useMunicipalities(governorateId?: string): Pick<Municipality, 'id' | 'name' | 'pcode' | 'coordinates'>[];
+export function useNeighborhoods(municipalityId: string): Neighborhood[];
+export function useSyriaSearch(query: string): Array<{
+    type: 'governorate' | 'district' | 'municipality' | 'neighborhood';
+    item: any;
+    municipalityId?: string;
+}>;

package/src/react/index.js

@@ -0,0 +1,41 @@
+import { useMemo } from 'react';
+import * as syria from '../index.js';
+
+/**
+ * Returns all 14 Syrian governorates.
+ */
+export function useGovernorates() {
+  return useMemo(() => syria.getGovernorates(), []);
+}
+
+/**
+ * Returns districts for a given governorate ID.
+ * @param {string} governorateId 
+ */
+export function useDistricts(governorateId) {
+  return useMemo(() => syria.getDistricts(governorateId), [governorateId]);
+}
+
+/**
+ * Returns all municipalities for a given governorate ID.
+ * @param {string} governorateId 
+ */
+export function useMunicipalities(governorateId) {
+  return useMemo(() => syria.getMunicipalities(governorateId), [governorateId]);
+}
+
+/**
+ * Returns all neighborhoods for a given municipality ID.
+ * @param {string} municipalityId 
+ */
+export function useNeighborhoods(municipalityId) {
+  return useMemo(() => syria.getNeighborhoods(municipalityId), [municipalityId]);
+}
+
+/**
+ * Real-time search across the entire hierarchical dataset.
+ * @param {string} query Search text (Arabic or English)
+ */
+export function useSyriaSearch(query) {
+  return useMemo(() => syria.search(query), [query]);
+}