Fortas Abdeldjalil
🚧 💻 👀
Zakaria Mansouri
🔧 👀
Oussama Bouchikhi
💻
Nasser Abachi
💻
Anurag sati
💻
HamdiAmine
💻
xxKeefer
💻
Joey Nguyen
💻
LOUKIL Mohamed Reda
🤔 💻
Fortas Oussama Ilyes
💻
Abdelmounaim TAZI
💻
Toumi abderrahmane
💻 💡
](https://join.slack.com/t/dzcode/shared_invite/zt-ek9kscb7-m8z_~cBjX79l~uchuABPFQ) [](https://www.npmjs.com/package/@dzcode-io/leblad) [](https://www.firsttimersonly.com/) [](https://codecov.io/gh/dzcode-io/leblad/branches) [](https://dashboard.stryker-mutator.io/reports/github.com/dzcode-io/leblad/develop) [](https://snyk.io/test/github/dzcode-io/leblad) [](https://github.com/dzcode-io/leblad/actions/workflows/codeql-analysis.yml)
[](#contributors-)
A library providing a list of Algerian administrative areas with many useful APIs.
## Getting started
### Usage
### Installation
```
npm install @dzcode-io/leblad --save
```
## API
#### getWilayaList(projection?: string[])
Returns a list of Algerian provinces (Wilayas)
**Arguments**
- `projection: string[]` (optional) Array of Wilaya Object attributes to keep.
**Examples**
```javascript
const { getWilayaList, getWilayaByZipCode } = require('@dzcode-io/leblad');
const allWilayasDetails = getWilayaList();
// if we only want the wilaya names for example:
const wilayasNames = getWilayaList(['name', 'name_ar', 'name_en']);
```
#### getWilayaByZipCode(zipCode: number, projection?: string[])
Returns a wilaya that includes the given zipCode.
**Arguments**
- `zipCode: number` (**required**) A zip code
- `projection: string[]` (optional) Array of Wilaya Object attributes to keep
**Examples**
```javascript
const { getWilayaByZipCode } = require('@dzcode-io/leblad');
// To get the wilaya that includes the zip code 1000, We can use getWilayaByZipCode
// This example will return Adrar { name: "Adrar", ...}
const wilaya = getWilayaByZipCode(1000);
// We can also select only attributes that we want, For example select name and mattricule:
const wilayaAttributes = getWilayaByZipCode(1000, ['name', 'mattricule']);
```
#### getWilayaByCode(wilayaCode: number, projection?: string[])
Takes a wilaya code (matricule) and returns the matching wilaya
**Arguments**
- `wilayaCode: number` (**required**) the Wilaya's "matricule"
- `projection: string[]` (optional) Array of Wilaya Object attributes
**Examples**
```javascript
const { getWilayaByCode } = require('@dzcode-io/leblad');
console.log(getWilayaByCode(31)); // will print the wilaya object ({name: "Oran"...})
```
##### getAdjacentWilayas(wilayaCode: number)
Takes a wilaya code (matricule) and returns a list of adjacent wilayas codes
**Arguments**
- `wilayaCode: number` (**required**) the Wilaya's "matricule"
**Examples**
```javascript
const { getAdjacentWilayas } = require('@dzcode-io/leblad');
console.log(getAdjacentWilayas(31)); // will print [46, 22, 29, 27]
```
#### getZipCodesForWilaya(wilayaCode: number)
Takes a wilaya code (matricule) and returns a list of Respective Zip-Codes for that wilaya
**Arguments**
- `wilayaCode: number` (**required**) the Wilaya's "matricule"
**Examples**
```javascript
const { getZipCodesForWilaya } = require('@dzcode-io/leblad');
console.log(getZipCodesForWilaya(31)); //returns list of zip codes for wilaya 31
```
#### getDairatsForWilaya(wilayaCode: number, projection?: string[])
Takes a wilaya code (matricule) ans returns list of all dairats of that wilaya.
**Arguments**
- `wilayaCode: number` (**required**) the Wilaya's "matricule"
- `projection: string[]` (optional) Array of Wilaya Object attributes to keep
**Examples**
```javascript
const { getDairatsForWilaya } = require('@dzcode-io/leblad');
console.log(getDairatsForWilaya(3)); //returns list of dairats for wilaya 3
```
#### getWilayaByPhoneCode(phoneCode: number, projection?: string[])
Takes a phone code and returns the matching wilaya.
**Arguments**
- `phoneCode: number | string` (**required**) the Wilaya's "phoneCode"
- `projection: string[]` (optional) Array of Wilaya Object attributes to keep
**Examples**
```javascript
const { getWilayaByPhoneCode } = require('@dzcode-io/leblad');
console.log(getWilayaByPhoneCode(34)); //will the wilaya object ({name: "Béjaïa"...})
console.log(getWilayaByPhoneCode('34')); //will return the same the wilaya object ({name: "Béjaïa"...})
```
#### getWilayaByDairaName(dairaName: String, projection?: string[])
Takes a daira name and returns the matching wilaya.
**Arguments**
- `dairaName: string` (**required**) the Wilaya's "dairaName" in en|fr|ar
- `projection: string[]` (optional) Array of Wilaya Object attributes to keep
**Examples**
```javascript
const { getWilayaByDairaName } = require('@dzcode-io/leblad');
console.log(getWilayaByDairaName('OUED RHIOU')); // will print the wilaya object ({name: "Relizane"...})
```
#### getBaladyiatsForDaira(dairaName: String)
Takes a daira name and returns the matching baladyiats.
**Arguments**
- `daira: string` (**required**) the Wilaya's "dairaName" in en|fr|ar
**Examples**
```javascript
const { getBaladyiatsForDaira } = require('@dzcode-io/leblad');
console.log(getBaladyiatsForDaira('ORAN')); // will return baladyiats for daira of "Oran"
```
#### getBaladyiatsForDairaCode(dairaCode: Number)
Takes a daira code and returns the matching baladyiats.
**Arguments**
- `daira: number` (**required**) the Wilaya's "dairaCode" in en|fr|ar
**Examples**
```javascript
const { getBaladyiatsForDairaCode } = require('@dzcode-io/leblad');
console.log(getBaladyiatsForDairaCode(31)); // will return baladyiats for daira of "Oran"
```
#### getPhoneCodesForWilaya(wilayaCode: number)
Takes a wilaya code (matricule) and returns a list of phone codes for given wilaya
**Arguments**
- `wilayaCode: number` (**required**) the Wilaya's "matricule"
**Examples**
```javascript
const { getPhoneCodesForWilaya } = require('@dzcode-io/leblad');
console.log(getPhoneCodesForWilaya(31)); //returns list of phone codes for wilaya 31
```
#### getPhoneCodeForWilaya(wilayaCode: number)
Takes a wilaya code (matricule) and returns the first phone code from a list of phone codes for given wilaya
**Arguments**
- `wilayaCode: number` (**required**) the Wilaya's "matricule"
**Examples**
```javascript
const { getPhoneCodeForWilaya } = require('@dzcode-io/leblad');
console.log(getPhoneCodeForWilaya(16)); //returns first phone code for wilaya 16
```
#### getBaladyiatsForWilaya(wilayaCode: number, projection?: string[])
Takes a wilaya code (mattricule) and returns array of Baladiyates of wilaya.
**Arguments**
- `wilayaCode: number` (**required**) the Wilaya's "matricule"
- `projection: string[]` (optional) Array of Baladyia Object attributes
**Examples**
```javascript
const { getBaladyiatsForWilaya } = require('@dzcode-io/leblad');
console.log(getBaladyiatsForWilaya(31)); // will print the baladyiats list ([{ code: 3125, name: 'AIN KERMA'..},{ code: 3105,name: 'ES SENIA',}])
```
#### getWilayaByBaladyiaName(baladyiaName: number, projection?: string[])
Takes a Baladyia name and returns wilaya in which baladyia is located.
**Arguments**
- `baladyiaName: number` (**required**) the Baladyia name
- `projection: string[]` (optional) Array of Wilaya Object attributes
**Examples**
```javascript
const { getWilayaByBaladyiaName } = require('@dzcode-io/leblad');
console.log(getWilayaByBaladyiaName('ES SENIA')); // will print the wilaya object ({name: "Oran"...})
```
#### getDairaByBaladyiaName(baladyiaName: number, projection?: string[])
Takes a Baladyia name and returns daira in which baladyia is located.
**Arguments**
- `baladyiaName: number` (**required**) the Baladyia name
- `projection: string[]` (optional) Array of Wilaya Object attributes
**Examples**
```javascript
const { getDairaByBaladyiaName } = require('@dzcode-io/leblad');
console.log(getDairaByBaladyiaName('ES SENIA')); // will print the daira object ({name: "ES SENIA"...})
```
## Helper methods
#### projectObject(data: (object|array), projection?: string[])
Return an object or an array of object with only data (example: Wilaya, Daira, Baladiya) attribute you select in the `projection` attributes array.
**Arguments**
- `data: (object|array)` (**required**) A data object or an array of data objects(Wilayas, Dairas, Baladiyas)
- `projection: string[]` (optional) Array of data Object attributes
**Examples**
```javascript
const { projectObject: projectWilaya } = require('@dzcode-io/leblad').utils;
...
const wilayasNames = projectWilaya(someWilayaObject, ['name', 'name_ar', 'name_en']);
```
#### isValidWilayaCode(code:number)
Check if a given wilaya code (matricule) is valid (i.e is an integer between 1 and 48).
**Arguments**
- `code: number` (**required**) Wilaya code
#### isValidZipCode(code:(number|string))
Check if a given zip code is valid (i.e is an integer between 1000 and 48073).
**Arguments**
- `code: (number|string)` (**required**) zip code
## Local development
#### Perquisites
Make sure you have:
- [Git](https://git-scm.com/)
- [Nodejs](https://nodejs.org/) version 10 or higher
#### Install the dependencies
```
npm install
```
#### Update the Wilayas dataset
```
npm run update-dataset
```
#### Testing
Simply run
```
npm test
```
Or this command for the `watch mode`:
```
npm run test.watch
```
You can also run [mutation tests](https://en.wikipedia.org/wiki/Mutation_testing) (using [Stryker-mutator](https://stryker-mutator.io/))
```
npm run test.mutation
```
## Contributors ✨
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):