african-states-and-tribes 1.1.2 → 2.0.0

package/.github/CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# Contributing to African States and Tribes
+
+:+1: :tada: First off, thanks for taking the time to contribute! :tada: :+1:
+
+The following is a set of guidelines for contributing to the **African States and Tribes** project. These are mostly guidelines, not strict rules—use your best judgment, and feel free to propose changes via a pull request.
+
+---
+
+## How Can I Contribute?
+
+### 🛠 Fixing Data Yourself
+
+If you've spotted incorrect or outdated data, feel free to correct it and raise a pull request.
+
+---
+
+### 🌍 Contributing to the Tribes Database
+
+- The African tribes database is located in the `src/data/africa/tribes` folder.
+- Each file in this folder represents a single country and is named using the [ISO 3166-1 alpha-2 code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
+- Refer to the `README.md` for details on the structure and meaning of the properties used in the tribes files.
+- You may suggest updates or improvements as needed.
+- If you're adding new data, including a reference or source will increase the chances of your pull request being accepted.
+
+---
+
+### 🗺 Contributing to the African Countries Database
+
+- The list of African countries can be found in the `src/data/africa/countries.json` file.
+- You may suggest updates or improvements to this file as needed.
+
+---
+
+### ✨ Suggesting or Implementing New Features
+
+- New features can be implemented in the `src/index.ts` file.
+- All new feature suggestions will be reviewed to ensure they align with the project’s goals.
+
+---
+
+
+
+
+## 📋 How to Contribute via Pull Request
+
+1. **Fork** the repository to your own GitHub account.
+2. **Clone** your forked repo locally:
+   ```bash
+   git clone https://github.com/your-username/african-states-and-tribes.git
+   cd african-states-and-tribes
+3. git checkout -b your-branch-name
+4. git commit -m "Short description of your change"
+5. git push origin your-branch-name
+6. Open a Pull Request from your branch to the main branch of the original repo.
+
+
+Thank you for helping make this project better! Happy contributing!

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,33 @@
+# Pull Request
+
+## Description
+
+Please include a summary of the changes and the related issue(s). Explain the motivation behind this PR and any context that might be useful.
+
+Fixes # (if applicable)
+
+## Type of Change
+
+- [ ] Bug fix (non-breaking change that fixes an issue)
+- [ ] New feature (non-breaking change that adds functionality)
+- [ ] Data update (new or updated tribe or country data)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation update
+
+## Checklist
+
+- [ ] My code follows the style guidelines of this project
+- [ ] I have performed a self-review of my changes
+- [ ] I have commented my code, particularly in hard-to-understand areas
+- [ ] I have added or updated relevant documentation
+- [ ] My changes generate no new warnings or errors
+- [ ] I have added tests that prove my fix is effective or that my feature works (if applicable)
+- [ ] New and existing unit tests pass locally with my changes
+
+## Screenshots / Data Samples (if applicable)
+
+Include any visuals or JSON snippets that help reviewers understand your changes.
+
+## Additional Notes
+
+Add any other relevant information, such as external references, related PRs, or anything you'd like the maintainers to know.

package/README.md

@@ -1,16 +1,42 @@
 # African-states-and-tribes
 
-This project provides comprehensive insights into African countries, the origins of various tribes, and their geographic distributions. Built to celebrate and document Africa’s rich multicultural landscape, it allows users to explore the continent’s diverse cultural heritage, discovering the roots and locations of countless ethnic groups across Africa.
+A lightweight zero-dependency JavaScript/TypeScript utility library for African countries and their corresponding states and tribes, dynamically loaded by country code. It provides structured access to comprehensive data on African countries and their administrative geography and ethnic groups.
+
+The library includes country-level metadata (such as name, capital, currency, phone code, flag, and ISO codes), supports geographic hierarchies including local government areas (LGAs) and other administrative subdivisions across all countries, and offers detailed tribal distributions by region or state, as well as major ethnic group data per country.
+
+<!-- A zero-dependency JavaScript library for structured access to African countries’ metadata, ethnic groups, and administrative divisions — including tribal distributions and local government areas. -->
+
+<!-- african-countries-data -->
+
+
+## 🚀 Features
+
+✅ List all African countries
+
+✅ Fetch a single country by its ISO code
+
+✅ Get state/tribal data for each country (on-demand)
+
+✅ Lightweight and async — loads only what you need
+
+✅ Simple, modular, and TypeScript-friendly
+
 
 # Install
-`npm i country-state-city`
+`npm i african-states-and-tribes`
 
 # Usage
 
   - ES6 Module usage
    
      ```js
-     import * as africanStates from 'african-states-and-tribes'
+     import { 
+        getCountries, 
+        getCountry, 
+        getCountryStates, 
+        getCountriesAndStates, 
+        getCountryAndState 
+    } from 'african-states-and-tribes'
      ```
 
   - ES5 Module usage
@@ -21,12 +47,12 @@ This project provides comprehensive insights into African countries, the origins
 
 # Docs
 
-  - **Get all African Countries**
+  - **Get all Countries** 
 
     ```js
-    import * as africanStates from 'african-states-and-tribes'
+    import { getCountries } from 'african-states-and-tribes'
 
-    africanStates.getCountries().then(countries =>{
+    getCountries().then(countries =>{
         console.log(countries)
     })
     ```
@@ -38,38 +64,60 @@ This project provides comprehensive insights into African countries, the origins
             {
                     phoneCode: 244,
                     capitalCity: "Luanda",
-                    colonialMaster:"",
-                    countryCode:"AO",
+                    colonialMaster: [
+                        {
+                            name: "Portugal",
+                            countryCode: "PT"
+                        }
+                    ],
+                    countryCode: "AO",
                     flagEmoji: "🇦🇴",
                     name: "Angola",
                     currency: "Angolan kwanza",
-                    currencyCode:"AOA",
-                    currencySymbol:"Kz",
+                    currencyCode: "AOA",
+                    currencySymbol: "Kz",
                     officialLanguage: "Portuguese",
-                    majorEthnicGroups:["Bakongo", "Chokwe", "Herero", "Humbi", "Kimbundu", "Mbundu", "Ngangela", "Ovimbundu"]
+                    majorEthnicGroups: ["Bakongo", "Mbundu", "Ovimbundu"],
+                    timezones: [
+                        {
+                            iana: "Africa/Luanda",
+                            gmtOffset: "+01:00"
+                        }
+                    ]
             },
             {
                     phoneCode: 229,
                     capitalCity: "Porto-Novo",
-                    colonialMaster:"",
-                    countryCode:"BJ",
+                    colonialMaster: [
+                        {
+                            name: "France",
+                            countryCode: "FR"
+                        }
+                    ],
+                    countryCode: "BJ",
                     flagEmoji: "🇧🇯",
                     name: "Benin",
                     currency: "West African CFA franc",
-                    currencyCode:"XOF",
-                    currencySymbol:"Fr",
+                    currencyCode: "XOF",
+                    currencySymbol: "Fr",
                     officialLanguage: "French",
-                    majorEthnicGroups:["Adja (Aja)","Bariba","Dendi (Songhai)","Fon (Dahomey)","Fulani","Lukpa","Tammari (Betammaribe)","Yoruba"]
-            },
+                    majorEthnicGroups: ["Bariba", "Fon (Dahomey)", "Yoruba"],
+                     timezones: [
+                        {
+                            iana: "Africa/Porto-Novo",
+                            gmtOffset: "+01:00"
+                        }
+                    ]
+            }
             ...
         ]
     ```
-  - **Get All African Countries + Tribal Data**
+  - **Get All African Countries + State/Tribal Data**
   
     ```js
-    import * as africanStates from 'african-states-and-tribes'
+    import { getCountriesAndStates } from 'african-states-and-tribes'
 
-    africanStates.getCountriesAndTribalData("NG").then(countries =>{
+    getCountriesAndStates().then(countries =>{
         console.log(countries)
     })
     ```
@@ -89,8 +137,8 @@ This project provides comprehensive insights into African countries, the origins
             currencyCode:"AOA",
             currencySymbol:"Kz",
             officialLanguage: "Portuguese",
-            majorEthnicGroups:["Bakongo", "Chokwe", "Herero", "Humbi", "Kimbundu", "Mbundu", "Ngangela", "Ovimbundu"]
-            tribalDistribution:[
+            majorEthnicGroups: ["Bakongo", "Mbundu", "Ovimbundu"],
+            states:[
                 {
                     capitalCity:"Caxito",
                     subdivisions:["Ambriz", "Bula Atumba", "Dande", "Dembos","Nambuangongo", "Pango Aluquém"],
@@ -122,9 +170,9 @@ This project provides comprehensive insights into African countries, the origins
   - **Get Specific Country by CountryCode**
 
     ```js
-    import * as africanStates from 'african-states-and-tribes'
+    import { getCountry } from 'african-states-and-tribes'
 
-    africanStates.getCountry("NG").then(country =>{
+    getCountry("NG").then(country =>{
         console.log(country)
     })
 
@@ -136,7 +184,12 @@ This project provides comprehensive insights into African countries, the origins
         {
             phoneCode: 234,
             capitalCity: "Abuja",
-            colonialMaster:"",
+            colonialMaster: [
+                {
+                    name: "United Kingdom",
+                    countryCode: "GB"
+                }
+            ],
             countryCode:"NG",
             flagEmoji: "🇳🇬",
             name: "Nigeria",
@@ -144,16 +197,22 @@ This project provides comprehensive insights into African countries, the origins
             currencyCode:"NGN",
             currencySymbol:"₦",
             officialLanguage: "English",
-            majorEthnicGroups:["Fulani", "Hausa","Kanuri","Ibibio", "Igbo","Ijaw", "Tiv","Yoruba"]
+            majorEthnicGroups:["Fulani", "Hausa", "Igbo", "Yoruba"],
+            timezones: [
+                {
+                    "iana": "Africa/Lagos",
+                    "gmtOffset": "+01:00"
+                }
+            ]
         }
 
     ```
-  - **Get Specific Country + Tribal Data by CountryCode**
+  - **Get Specific Country + State/Tribal Data by CountryCode**
 
     ```js
-    import * as africanStates from 'african-states-and-tribes'
+    import { getCountryAndState } from 'african-states-and-tribes'
 
-     africanStates.getCountryAndTribalData("NG").then(country =>{
+     getCountryAndState("NG").then(country =>{
         console.log(country)
     })
     ```
@@ -164,7 +223,12 @@ This project provides comprehensive insights into African countries, the origins
         {
             phoneCode: 234,
             capitalCity: "Abuja",
-            colonialMaster:"",
+            colonialMaster: [
+                {
+                    name: "United Kingdom",
+                    countryCode: "GB"
+                }
+            ],
             countryCode:"NG",
             flagEmoji: "🇳🇬",
             name: "Nigeria",
@@ -172,8 +236,8 @@ This project provides comprehensive insights into African countries, the origins
             currencyCode:"NGN",
             currencySymbol:"₦",
             officialLanguage: "English",
-            majorEthnicGroups:["Fulani", "Hausa","Kanuri","Ibibio", "Igbo","Ijaw", "Tiv","Yoruba"]
-            tribalDistribution:[
+            majorEthnicGroups:["Fulani", "Hausa", "Igbo", "Yoruba"],
+            states:[
                  {
                     capitalCity:"Umuahia",
                     subdivisions: ["Aba North", "Aba South", "Arochukwu", "Bende", "Ikwuano", "Isiala Ngwa North", "Isiala Ngwa South", "Isuikwuato", "Obi Ngwa", "Ohafia", "Osisioma", "Ugwunagbo", "Ukwa East", "Ukwa West", "Umuahia North", "Umuahia South"],
@@ -189,12 +253,12 @@ This project provides comprehensive insights into African countries, the origins
 
     ```
 
-  - **Get a Country's Tribal Data Only**
+  - **Get a Country's State/Tribal Data Only**
 
     ```js
-    import * as africanStates from 'african-states-and-tribes'
+    import { getCountryStates } from 'african-states-and-tribes'
 
-    africanStates.getTribesByCountry("NG").then(tribes =>{
+    getCountryStates("NG").then(tribes =>{
         console.log(tribes)
     })
     ```
@@ -228,6 +292,12 @@ This project provides comprehensive insights into African countries, the origins
     ```
 
 
+    Notes
+    - All functions are asynchronous – you must use await or .then()
+
+    - Tribe/state data is dynamically imported using import() for performance
+
+
 
     | Key                                    | Description                        
     |----------------------------------------|-----------------------------
@@ -241,74 +311,16 @@ This project provides comprehensive insights into African countries, the origins
     | currencySymbol                         | Country's official currency symbol
     | officialLanguage                       | Country's official language
     | majorEthnicGroups                      | Major ethnic found in the country
-    | tribalDistribution                     | Array containing country's tribal origin grouped by state/region/province found in. 
-    | tribalDistribution.capitalCity         | state/region/province capital city
-    | tribalDistribution.subdivisions        | state/region/province administrative sub divisions such as Local Government
-    | tribalDistribution.geoPoliticalZone    | Geopolitical zone in which the state/region/province falls under
-    | tribalDistribution.location            | state/region/province location on country's map
-    | tribalDistribution.name                | state/region/province
-    | tribalDistribution.stateCode           | state/region/province official code
-    | tribalDistribution.tribes              | Tribes found in state/region/province
-    | tribalDistribution.type                | type of either state/region/province
-
-
-
-
-# Countries Covered.
-- Angola
-- Algeria
-- Benin - Departments/Communes
-- Botswana
-- Burkina Faso
-- Burundi
-- Cabo Verde
-- Cameroon
-- Central African Republic
-- Chad
-- Comoros
-- Democratic Republic of the Congo
-- Republic of the Congo
-- Cote D'Ivoire
-- Djibouti
-- Egypt
-- Equatorial Guinea
-- Eritrea
-- Ethiopia
-- Gabon
-- Ghana
-- Gambia
-- Guinea
-- Guinea-Bissau
-- Kenya
-- Lesotho
-- Liberia
-- Libya
-- Madagascar
-- Malawi
-- Mali
-- Mauritania
-- Mauritius
-- Morocco
-- Mozambique
-- Namibia
-- Niger
-- Nigeria - States/Local Government
-- Rwanda
-- Sao Tome And Principe
-- Senegal
-- Seychelles
-- Sierra Leone
-- Somalia - Regions/Districts
-- South Africa
-- South Sudan
-- Sudan
-- Eswatini
-- Tanzania
-- Togo
-- Tunisia
-- Uganda
-- Zambia
-- Zimbabwe
+    | states                                 | Array containing country's states/provinces/regions
+    | states.capitalCity                     | state/region/province capital city
+    | states.subdivisions                    | state/region/province administrative sub divisions such as Local Government
+    | states.geoPoliticalZone                | Geopolitical zone in which the state/region/province falls under
+    | states.location                        | state/region/province location on country's map
+    | states.name                            | state/region/province
+    | states.stateCode                       | state/region/province official code
+    | states.tribes                          | Tribes found in state/region/province
+    | states.type                            | type of either state/region/province
+
 
 # Data Sources
 - https://www.vanguardngr.com/2017/05/full-list-of-all-371-tribes-in-nigeria-states-where-they-originate/

package/SECURITY.md

@@ -5,7 +5,8 @@
 | Version | Supported          |
 | ------- | ------------------ |
 | 1.0.0   | :white_check_mark: |
+| 1.1.0   | :white_check_mark: |
+| 1.1.1   | :white_check_mark: |
+| 1.1.2   | :white_check_mark: |
 
-:x:   
-
-## Reporting a Vulnerability
+<!-- :x:    -->

package/dist/{AO-LQ4VRH4F.mjs → AO-KTWONNYZ.mjs}

@@ -79,7 +79,7 @@ var AO = {
     location: "South",
     name: "Cunene",
     stateCode: "CNN",
-    tribes: ["Herero", "Kwanyama", "Nyaneka-Nkhumbi", "Ovambo (Ovimbundu)"],
+    tribes: ["Herero", "Kwanyama", "Nyaneka-Nkhumbi", "Ovimbundu"],
     type: "province"
   },
   HUAMBO: {

package/dist/{BF-BZ7WXNF3.mjs → BF-O7TBSCCA.mjs}

@@ -9,7 +9,7 @@ var BF = {
     location: "North West",
     name: "Boucle du Mouhoun",
     stateCode: "BM",
-    tribes: ["Mossi", "Gourmantch\xE9", "Bobo"],
+    tribes: ["Bobo", "Gourmantch\xE9", "Mossi"],
     type: "region"
   },
   CASCADES: {
@@ -19,7 +19,7 @@ var BF = {
     location: "South West",
     name: "Cascades",
     stateCode: "CA",
-    tribes: ["Bobo", "Mossi", "Gourmantch\xE9"],
+    tribes: ["Bobo", "Gourmantch\xE9", "Mossi"],
     type: "region"
   },
   CENTRE: {

package/dist/{CV-B7NIY45I.mjs → CV-UT67RQS3.mjs}

@@ -9,7 +9,7 @@ var CV = {
     location: "North",
     name: "Boa Vista",
     stateCode: "BV",
-    tribes: ["Cape Verdean"],
+    tribes: ["Creole"],
     type: "municipality"
   },
   BRAVA: {
@@ -19,7 +19,7 @@ var CV = {
     location: "South",
     name: "Brava",
     stateCode: "BR",
-    tribes: ["Cape Verdean"],
+    tribes: ["Creole"],
     type: "municipality"
   },
   "CH\xC3O BOM": {
@@ -29,7 +29,7 @@ var CV = {
     location: "North",
     name: "Ch\xE3o Bom",
     stateCode: "CB",
-    tribes: ["Cape Verdean"],
+    tribes: ["Creole"],
     type: "municipality"
   },
   CONCEI\u00C7\u00C3O: {
@@ -39,7 +39,7 @@ var CV = {
     location: "North",
     name: "Concei\xE7\xE3o",
     stateCode: "CE",
-    tribes: ["Cape Verdean"],
+    tribes: ["Creole"],
     type: "municipality"
   },
   FOGO: {
@@ -49,7 +49,7 @@ var CV = {
     location: "South",
     name: "Fogo",
     stateCode: "FO",
-    tribes: ["Cape Verdean"],
+    tribes: ["Creole"],
     type: "municipality"
   },
   MAIO: {
@@ -59,7 +59,7 @@ var CV = {
     location: "South",
     name: "Maio",
     stateCode: "MA",
-    tribes: ["Cape Verdean"],
+    tribes: ["Creole"],
     type: "municipality"
   },
   PAUL: {
@@ -69,7 +69,7 @@ var CV = {
     location: "North West",
     name: "Paul",
     stateCode: "PA",
-    tribes: ["Cape Verdean"],
+    tribes: ["Creole"],
     type: "municipality"
   },
   PRAIA: {
@@ -79,7 +79,7 @@ var CV = {
     location: "South",
     name: "Praia",
     stateCode: "PR",
-    tribes: ["Cape Verdean"],
+    tribes: ["Creole"],
     type: "municipality"
   },
   "RIBEIRA GRANDE": {
@@ -89,7 +89,7 @@ var CV = {
     location: "North West",
     name: "Ribeira Grande",
     stateCode: "RG",
-    tribes: ["Cape Verdean"],
+    tribes: ["Creole"],
     type: "municipality"
   },
   "RIBEIRA GRANDE DE SANTIAGO": {
@@ -99,7 +99,7 @@ var CV = {
     location: "South",
     name: "Ribeira Grande de Santiago",
     stateCode: "RG",
-    tribes: ["Cape Verdean"],
+    tribes: ["Creole"],
     type: "municipality"
   },
   "RIBEIRA PRATA": {
@@ -109,7 +109,7 @@ var CV = {
     location: "North",
     name: "Ribeira Prata",
     stateCode: "RP",
-    tribes: ["Cape Verdean"],
+    tribes: ["Creole"],
     type: "municipality"
   },
   "SANTA CATARINA": {
@@ -119,7 +119,7 @@ var CV = {
     location: "South",
     name: "Santa Catarina",
     stateCode: "SC",
-    tribes: ["Cape Verdean"],
+    tribes: ["Creole"],
     type: "municipality"
   },
   "SANTA CRUZ": {
@@ -129,7 +129,7 @@ var CV = {
     location: "South",
     name: "Santa Cruz",
     stateCode: "SC",
-    tribes: ["Cape Verdean"],
+    tribes: ["Creole"],
     type: "municipality"
   },
   "SANTO ANT\xC3O": {
@@ -139,7 +139,7 @@ var CV = {
     location: "North West",
     name: "Santo Ant\xE3o",
     stateCode: "SA",
-    tribes: ["Cape Verdean"],
+    tribes: ["Creole"],
     type: "municipality"
   },
   "SANTO MIGUEL": {
@@ -149,7 +149,7 @@ var CV = {
     location: "North East",
     name: "Santo Miguel",
     stateCode: "SM",
-    tribes: ["Cape Verdean"],
+    tribes: ["Creole"],
     type: "municipality"
   },
   "S\xC3O DOMINGOS": {
@@ -159,7 +159,7 @@ var CV = {
     location: "South",
     name: "S\xE3o Domingos",
     stateCode: "SD",
-    tribes: ["Cape Verdean"],
+    tribes: ["Creole"],
     type: "municipality"
   },
   "S\xC3O FILIPE": {
@@ -169,7 +169,7 @@ var CV = {
     location: "South",
     name: "S\xE3o Filipe",
     stateCode: "SF",
-    tribes: ["Cape Verdean"],
+    tribes: ["Creole"],
     type: "municipality"
   },
   "S\xC3O NICOLAU": {
@@ -179,7 +179,7 @@ var CV = {
     location: "North",
     name: "S\xE3o Nicolau",
     stateCode: "SN",
-    tribes: ["Cape Verdean"],
+    tribes: ["Creole"],
     type: "municipality"
   },
   "S\xC3O VICTOR": {
@@ -189,7 +189,7 @@ var CV = {
     location: "North",
     name: "S\xE3o Victor",
     stateCode: "SV",
-    tribes: ["Cape Verdean"],
+    tribes: ["Creole"],
     type: "municipality"
   },
   "S\xC3O VICENTE": {
@@ -199,7 +199,7 @@ var CV = {
     location: "North",
     name: "S\xE3o Vicente",
     stateCode: "SV",
-    tribes: ["Cape Verdean"],
+    tribes: ["Creole"],
     type: "municipality"
   },
   TARFAYA: {
@@ -209,7 +209,7 @@ var CV = {
     location: "North",
     name: "Tarfaya",
     stateCode: "TA",
-    tribes: ["Cape Verdean"],
+    tribes: ["Creole"],
     type: "municipality"
   },
   TAVARES: {
@@ -219,7 +219,7 @@ var CV = {
     location: "North",
     name: "Tavares",
     stateCode: "TA",
-    tribes: ["Cape Verdean"],
+    tribes: ["Creole"],
     type: "municipality"
   },
   TOMBO: {
@@ -229,7 +229,7 @@ var CV = {
     location: "North",
     name: "Tombo",
     stateCode: "TO",
-    tribes: ["Cape Verdean"],
+    tribes: ["Creole"],
     type: "municipality"
   }
 };