damascus 1.2.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,4 +1,4 @@
-# Syria Regions (focusing on 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]
@@ -7,7 +7,11 @@
 [![Damascus package][npm-dm]][damascus]
 [![Coverage Status][coveralls-badge]][coveralls]
 
-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.
+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). 
+
+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
 
@@ -16,64 +20,70 @@ This package is distributed via npm:
 npm install damascus
 ```
 
-## Usage (ES Modules & TypeScript)
+## 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, getMunicipalities, getNeighborhoods, SearchResult } from 'damascus';
+import { search, getAll, getGovernorates, getDistricts, getMunicipalities, getNeighborhoods } from 'damascus';
 
 // 1. Search API (Perfect for Autocomplete)
-const result: SearchResult[] = search('دمشق');
-
-// 2. Get all structured data
-const allData = getAll();
+const result = search('دمشق');
 
-// 3. Get an array of the 14 Syrian governorates
+// 2. Get the 14 Syrian governorates
 const governorates = getGovernorates();
 /* 
 [
-  { id: 'dam', name: { en: 'Damascus', ar: 'دمشق' } },
-  { id: 'ale', name: { en: 'Aleppo', ar: 'حلب' } },
+  { 
+    id: 'dam', 
+    pcode: 'SY01', 
+    coordinates: { lat: 33.5138, lng: 36.2765 },
+    name: { en: 'Damascus', 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: 'باب توما' } },
-  ...
-]
-*/
+// 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');
 ```
 
-### Legacy CommonJS Usage
-If you are still using CommonJS:
-```javascript
-const syria = require('damascus');
-const searchResults = syria.search('Bab Tuma'); 
+## 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
 
-- **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.
+- **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**: Includes type definitions (`.d.ts`) out of the box for excellent IDE support.
-- **Backward Compatible**: Maintains support for legacy `getDistricts()` API.
+- **TypeScript Support**: First-class types mapping the entire hierarchy.
 
 ## 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.
+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/github/actions/workflow/status/hadabo/damascus/ci.yml?style=flat-square
 [build]: https://github.com/hadabo/damascus/actions

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "damascus",
-  "version": "1.2.0",
+  "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"
+    ".": "./src/index.js",
+    "./react": "./src/react/index.js"
   },
   "type": "module",
   "engines": {
@@ -20,6 +21,7 @@
     "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": {
@@ -44,6 +46,9 @@
   },
   "homepage": "https://github.com/hadabo/damascus#readme",
   "dependencies": {},
+  "peerDependencies": {
+    "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+  },
   "devDependencies": {
     "chai": "^5.1.1",
     "commitizen": "^4.3.0",

package/src/index.d.ts

@@ -3,26 +3,38 @@ export interface LocalizedName {
   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;
-  municipalities?: Municipality[];
   districts?: District[];
 }
 

package/src/index.js

@@ -1,9 +1,4 @@
-import { readFileSync } from 'fs'
-import { fileURLToPath } from 'url'
-import { dirname, join } from 'path'
-
-const __dirname = dirname(fileURLToPath(import.meta.url))
-const syriaData = JSON.parse(readFileSync(join(__dirname, 'syria.json'), 'utf8'))
+import syriaData from './syria.js'
 
 function getAll () {
   return syriaData
@@ -20,39 +15,31 @@ 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 || []
   }
 
   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') {
+function getMunicipalities (governorateId = 'gov-damascus') {
   const gov = syriaData.find(g => g.id === governorateId)
-  if (!gov || !gov.municipalities) return []
-  return gov.municipalities.map(m => ({ id: m.id, name: m.name }))
+  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.municipalities) {
-      const mun = gov.municipalities.find(m => m.id === municipalityId)
-      if (mun) return mun.neighborhoods || []
+    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 []
@@ -65,7 +52,7 @@ function search (query) {
 
   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 } })
+      results.push({ type: 'governorate', item: { id: gov.id, name: gov.name, pcode: gov.pcode, coordinates: gov.coordinates } })
     }
 
     if (gov.districts) {
@@ -73,18 +60,18 @@ function search (query) {
         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 })
+        
+        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 })
+                }
+              })
             }
           })
         }

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]);
+}