african-states-and-tribes 1.1.3 → 2.1.0

package/README.md

@@ -1,16 +1,83 @@
 # 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
+
+✅ **NEW:** Modular imports — import only specific countries to reduce bundle size
+
 
 # Install
 `npm i african-states-and-tribes`
 
+# 📚 Documentation
+
+- [Modular Imports Guide](./MODULAR_IMPORTS.md) - Complete guide on using modular imports to optimize bundle size
+- [Usage Examples](./EXAMPLES.md) - Real-world examples and use cases
+
 # Usage
 
+## 🎯 Modular Imports (Recommended for Bundle Size Optimization)
+
+Import only the countries you need to keep your bundle size minimal:
+
+```js
+// Import specific country
+import { getCountry, getStates, getCountryAndStates } from 'african-states-and-tribes/countries/ng';
+
+// Get Nigeria data
+const nigeria = await getCountry();
+console.log(nigeria); // { name: 'Nigeria', countryCode: 'NG', ... }
+
+// Get Nigeria states/tribes
+const states = await getStates();
+console.log(states); // [{ name: 'Abia', tribes: ['Igbo'], ... }, ...]
+
+// Get Nigeria with states
+const nigeriaWithStates = await getCountryAndStates();
+console.log(nigeriaWithStates); // { name: 'Nigeria', states: [...], ... }
+```
+
+**Bundle Size Benefits:**
+- Default import (all countries): **~337KB**
+- Single country (modular): **~44KB average** (87% smaller!)
+- Multiple countries scale linearly
+
+See [EXAMPLES.md](./EXAMPLES.md) for more use cases including React, Next.js, and lazy loading.
+
+
+**Available country codes for modular imports:**
+`ao`, `bf`, `bi`, `bj`, `bw`, `cd`, `cf`, `cg`, `ci`, `cm`, `cv`, `dj`, `dz`, `eg`, `er`, `et`, `ga`, `gh`, `gm`, `gn`, `gq`, `gw`, `ke`, `km`, `lr`, `ls`, `ly`, `ma`, `mg`, `ml`, `mr`, `mu`, `mw`, `mz`, `na`, `ne`, `ng`, `rw`, `sc`, `sd`, `sl`, `sn`, `so`, `ss`, `st`, `sz`, `td`, `tg`, `tn`, `tz`, `ug`, `za`, `zm`, `zw`
+
+## 📦 Default Usage (All Countries)
+
   - 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 +88,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 +105,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 +178,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 +211,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 +225,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 +238,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 +264,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 +277,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 +294,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)
     })
     ```
@@ -227,6 +332,53 @@ This project provides comprehensive insights into African countries, the origins
       ]
     ```
 
+  - **Get a Tribe Region**
+
+    ```js
+    import { getTribeRegion } from 'african-states-and-tribes'
+
+     getTribeRegion("Yoruba").then(regions =>{
+        console.log(regions)
+    })
+    ```
+
+    Output:
+
+    ```
+        [
+            {
+                capitalCity: 'Kandi',
+                country: 'Benin',
+                countryCode: 'BJ',
+                geoPoliticalZone: '',
+                location: 'North East',
+                name: 'Alibori',
+                stateCode: '',
+                subdivisions: [],
+                tribes: ['Bariba', 'Boko', 'Dendi (Songhai)', 'Fulani', 'Gurma', 'Kyenga', 'Mokole Yoruba'],
+                type: 'department'
+            },
+            {
+                capitalCity: 'Allada',
+                country: 'Benin',
+                countryCode: 'BJ',
+                geoPoliticalZone: '',
+                location: 'South Centre',
+                name: 'Atlantique',
+                stateCode: '',
+                subdivisions: [],
+                tribes: [ 'Adja (Aja)', 'Ayizo', 'Tofin', 'Fon (Dahomey)', 'Yoruba' ],
+                type: 'department'
+            },
+            ...
+        ]
+    ```
+
+    Notes
+    - All functions are asynchronous – you must use await or .then()
+
+    - Tribe/state data is dynamically imported using import() for performance
+
 
 
     | Key                                    | Description                        
@@ -241,77 +393,19 @@ 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/
 - https://euaa.europa.eu/
 - https://www.citypopulation.de/
-- https://www.odsef.fss.ulaval.ca/sites/odsef.fss.ulaval.ca/files/odsef_assani_web.pdf
+- https://www.odsef.fss.ulaval.ca/sites/odsef.fss.ulaval.ca/files/odsef_assani_web.pdf

package/dist/{AO-LQ4VRH4F.mjs → AO-3WUV6HS7.mjs}

@@ -1,4 +1,4 @@
-import "./chunk-4UEJOM6W.mjs";
+import "./chunk-6X3JIUEO.mjs";
 
 // src/data/africa/tribes/AO.json
 var AO = {
@@ -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-GZ45LRSN.mjs}

@@ -1,4 +1,4 @@
-import "./chunk-4UEJOM6W.mjs";
+import "./chunk-6X3JIUEO.mjs";
 
 // src/data/africa/tribes/BF.json
 var BF = {
@@ -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/{BI-DLK4YMGO.mjs → BI-3GCTK7CF.mjs}

@@ -1,4 +1,4 @@
-import "./chunk-4UEJOM6W.mjs";
+import "./chunk-6X3JIUEO.mjs";
 
 // src/data/africa/tribes/BI.json
 var BI = {

package/dist/{BJ-PNML7KGU.mjs → BJ-4AJ2EFGG.mjs}

@@ -1,4 +1,4 @@
-import "./chunk-4UEJOM6W.mjs";
+import "./chunk-6X3JIUEO.mjs";
 
 // src/data/africa/tribes/BJ.json
 var BJ = {

package/dist/{BW-CNU7L4NH.mjs → BW-AN7LIVOT.mjs}

@@ -1,4 +1,4 @@
-import "./chunk-4UEJOM6W.mjs";
+import "./chunk-6X3JIUEO.mjs";
 
 // src/data/africa/tribes/BW.json
 var BW = {

package/dist/{CD-3L2NXQVL.mjs → CD-JYCWONXN.mjs}

@@ -1,4 +1,4 @@
-import "./chunk-4UEJOM6W.mjs";
+import "./chunk-6X3JIUEO.mjs";
 
 // src/data/africa/tribes/CD.json
 var CD = {

package/dist/{CF-ESX77N6V.mjs → CF-L6ZKGUE2.mjs}

@@ -1,4 +1,4 @@
-import "./chunk-4UEJOM6W.mjs";
+import "./chunk-6X3JIUEO.mjs";
 
 // src/data/africa/tribes/CF.json
 var CF = {

package/dist/{CG-VO3X7LDQ.mjs → CG-L6Q7VBRE.mjs}

@@ -1,4 +1,4 @@
-import "./chunk-4UEJOM6W.mjs";
+import "./chunk-6X3JIUEO.mjs";
 
 // src/data/africa/tribes/CG.json
 var CG = {

package/dist/{CI-GS6CFDT3.mjs → CI-OKLEG4C6.mjs}

@@ -1,4 +1,4 @@
-import "./chunk-4UEJOM6W.mjs";
+import "./chunk-6X3JIUEO.mjs";
 
 // src/data/africa/tribes/CI.json
 var CI = {

package/dist/{CM-BTFLGGR5.mjs → CM-5U7UTSLM.mjs}

@@ -1,4 +1,4 @@
-import "./chunk-4UEJOM6W.mjs";
+import "./chunk-6X3JIUEO.mjs";
 
 // src/data/africa/tribes/CM.json
 var CM = {