mozambique-utils
Version:
Easy to use parsers and validators for mozambican (🇲🇿) data-type formatted strings.
393 lines (303 loc) • 14 kB
Markdown
# mozambique-utils.js
Easy to use parsers and validators for mozambican (🇲🇿) data-type formatted strings.
[](https://npmjs.com/mozambique-utils)
## Table of contents
- [Installation and Usage](#installation-and-usage)
- [NPM](#using-npm)
- [Browser (CDN)](#in-a-browser)
- [API](#api)
<!-- isLandlineNumberValid(number [, options]) -->
- [`isLandlineNumberValid`](#islandlinenumbervalidnumber--options)
- [`isMobileNumberValid`](#ismobilenumbervalidnumber--options)
- [`isNUITValid`](#isnuitvalidnuit)
- [`isIBANValid`](#isibanvalidiban)
- [`parseMobileNumber`](#parsemobilenumbernumber)
- [`parseLandlineNumber`](#parselandlinenumbernumber)
- [Contributing](#contributing)
## Installation and Usage
#### Using npm
```bash
npm install mozambique-utils
```
```javascript
const mozambiqueUtils = require("mozambique-utils"); // -> No ES6
// import mozambiqueUtils from "mozambique-utils"; // -> or with ES6
mozambiqueUtils.isNUITValid("300010125"); //-> true
```
#### In a browser
This library can be loaded as a standalone script, which will then be made available through the `mozambiqueUtils` global object.
```html
<script src="https://unpkg.com/mozambique-utils@1.1.1/dist/mozambique-utils.js"></script>
<!--
Or use the minified version:
<script src="https://unpkg.com/mozambique-utils@1.1.1/dist/mozambique-utils.min.js"></script>
-->
<script type="text/javascript">
<!-- Usage -->
mozambiqueUtils.isNUITValid("300010125"); //=> true
</script>
```
## API
### `isLandlineNumberValid(number [, options])`
Check if a string is a valid mozambican landline number.
Returns `true` if valid, otherwise `false`.
###### number
The number to check. Must be of type string and can contain dashes or spaces.\
Will throw if not of type string.
###### options
An object that defaults to:
```javascript
{
allowedRegions: [],
countryCode: "optional"
}
```
| Option | Type | Accepted value(s) | Description |
| -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| allowedRegions | string[] | `tete` , `pemba`, `beira`, `chokwe`, `manica`, `xai-xai`, `maputo`, `nampula`, `lichinga`, `inhambane`, `quelimane`, `vilanculos` | List of regions to limit the validation on. If passed an emtpy array, it will validate for all regions. |
| countryCode | string | `optional`, `required`, `off` | `optional`: the country code in the number being validated is optional.<br>`required` only return true if the number includes the country code.<br>`off` only return true if the number does not include the country code.<br><br>The country code can be in either `+258` or `00258` or `258` format. |
##### Examples:
```javascript
mutils.isLandlineNumberValid("21201321"); //=> true
mutils.isLandlineNumberValid("21 203 123"); //=> true
mutils.isLandlineNumberValid("26-203-123"); //=> true
mutils.isLandlineNumberValid("+25824201321"); //=> true
mutils.isLandlineNumberValid("0025829320123"); //=> true
mutils.isLandlineNumberValid("25828123230"); //=> true
mutils.isLandlineNumberValid("841234567"); //=> false
mutils.isLandlineNumberValid("21201321", {
allowedRegions: ["beira", "tete", "chokwe"],
}); //=> false
mutils.isLandlineNumberValid("+25821201321", {
allowedRegions: ["maputo"],
countryCode: "required",
}); //=> true
mutils.isLandlineNumberValid("+25821201321", {
countryCode: "off",
}); //=> false
```
### `isMobileNumberValid(number [, options])`
Check if a string is a valid mozambican mobile number.\
Will throw if not of type string.\
Returns `true` if valid, otherwise `false`.
###### number
The mobile number to check. Must be of type string and can contain dashes or spaces.\
Will throw if not of type string.
###### options
An object that defaults to:
```javascript
{
allowedOperators: [],
countryCode: "optional"
}
```
| Option | Type | Accepted value(s) | Description |
| ---------------- | -------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| allowedOperators | string[] | `vodacom`, `tmcel`, `movitel` | List of mobile network operators to limit the validation on. If passed an emtpy array, it will validate for all network operators. |
| countryCode | string | `optional`, `required`, `off` | `optional`: the country code in the number being validated is optional.<br>`required` only return true if the number includes the country code.<br>`off` only return true if the number does not include the country code.<br><br>The country code can be in either `+258` or `00258` or `258` format. |
##### Examples:
```javascript
mutils.isMobileNumberValid("821234567"); //=> true
mutils.isMobileNumberValid("84 123 4567"); //=> true
mutils.isMobileNumberValid("84-123-4567"); //=> true
mutils.isMobileNumberValid("+258841234567"); //=> true
mutils.isMobileNumberValid("00258861234567"); //=> true
mutils.isMobileNumberValid("258871234567"); //=> true
mutils.isMobileNumberValid("811234567"); //=> false
mutils.isMobileNumberValid("841234567", {
allowedOperators: ["tmcel", "movitel"],
}); //=> false
mutils.isMobileNumberValid("+258841234567", {
allowedOperators: ["vodacom"],
countryCode: "required",
}); //=> true
mutils.isMobileNumberValid("+258841234567", {
countryCode: "off",
}); //=> false
```
### `isNUITValid(nuit)`
Check if a string is a valid mozambican [Número Único de Identificação Tributária (Taxpayer's Single Identification Number)](http://www.at.gov.mz/por/Perguntas-Frequentes2/NUIT).
Returns `true` if valid, otherwise `false`.
###### nuit
The nuit number to check. Must be of type string and can contain dashes or spaces.\
Will throw if not of type string.
##### Examples:
```javascript
mutils.isNUITValid("12345678"); //=> true
mutils.isNUITValid("1343"); //=> false
mutils.isNUITValid("348908989092"); //=> false
```
### `isIBANValid(iban)`
Check if a string is a valid mozambican formatted [International Bank Account Number - IBAN](https://en.wikipedia.org/wiki/International_Bank_Account_Number).\
Returns `true` for a valid mozambican formatted IBAN according to the [ISO 13616](https://www.iso.org/standard/81090.html), otherwise `false`.
###### iban
The mozambican iban to check.\
Must be of type string and can contain dashes or spaces.\
Will throw if not of type string.
##### Examples:
```javascript
// An example of a valid mozambican IBAN
// MZ59000301080016367102371
mutils.isIBANValid("MZ59000301080016367102371"); //=> true
mutils.isIBANValid("GB98BARC20032669387723"); //=> false
```
### `parseMobileNumber(number)`
Parse any mozambican mobile number. Returns:
```javascript
{
valid: boolean, // if the number being parsed is valid or not
data: {
number: string, // the number being parsed.
localFormat: string, // the number being parsed, formatted for national usage.
internationalFormat: string, // the number being parsed, formatted for international usage.
includesCountryCode: boolean, // does the number being parsed contain country code?
nationalDestinationCode: string, // the national destination code of the network operator.
operator: {
name: string, // long name of the network operator.
shortname: string // short name of the network operator.
},
lineType: "mobile" // the type of the line of the number being parsed.
}
}
```
When an invalid number is parsed, the value of `data` in the return object will be `null`.
###### number
The mobile number to check. Must be of type string and can contain dashes or spaces.
##### Examples:
```javascript
mutils.parseMobileNumber("+258-841234567");
/*
{
valid: true
data: {
number: "+258-841234567",
localFormat: "841234567",
internationalFormat: "+258841234567",
includesCountryCode: true,
nationalDestinationCode: "84",
operator: {
name: "Vodacom Moçambique",
shortname: "Vodacom"
},
lineType: "mobile"
}
}
*/
mutils.parseMobileNumber("831234567");
/*
{
valid: true
data: {
number: "831234567",
localFormat: "831234567",
internationalFormat: "+258831234567",
includesCountryCode: false,
nationalDestinationCode: "83",
operator: {
name: "Moçambique Telecom, S.A.",
shortname: "Tmcel"
},
lineType: "mobile"
}
}
*/
mutils.parseMobileNumber("8102392");
/*
{
valid: false,
data: null
}
*/
```
### `parseLandlineNumber(number)`
Parse any mozambican landline number. Returns:
```javascript
{
valid: boolean, // if the number being parsed is valid or not
data: {
number: string, // the number being parsed.
localFormat: string, // the number being parsed, formatted for national usage.
internationalFormat: string, // the number being parsed, formatted for international usage.
includesCountryCode: boolean, // does the number being parsed contain country code?
nationalDestinationCode: string, // the area code.
operator: {
name: string, // long name of the network operator.
shortname: string // short name of the network operator.
},
region: string, // the region where the (national destination code) area code is linked to.
lineType: "mobile" // the type of the line of the number being parsed.
}
}
```
When an invalid number is parsed, the value of `data` in the return object will be `null`.
###### number
The mobile number to check. Must be of type string and can contain dashes or spaces.\
Will throw if not of type string.
##### Examples:
```javascript
mutils.parseLandlineNumber("+258 21 351100");
/*
{
valid: true,
data: {
number: "+258 21 351100",
localFormat: "21351100",
internationalFormat: "+25821351100",
includesCountryCode: true,
nationalDestinationCode: "21",
operator: {
name: "Moçambique Telecom, S.A.",
shortname: "Tmcel"
},
region: "maputo",
lineType: "landline"
}
}
*/
mutils.parseLandlineNumber("29320123");
/*
{
valid: true,
data: {
number: "29320123",
localFormat: "29320123",
internationalFormat: "+25829320123",
includesCountryCode: false,
nationalDestinationCode: "293",
operator: {
name: "Moçambique Telecom, S.A.",
shortname: "Tmcel"
},
region: "inhambane",
lineType: "landline"
}
}
*/
mutils.parseLandlineNumber("841234567");
/*
{
valid: false,
data: null
}
*/
```
## Contributing
##### Bug Reports & Feature Requests
Please use the issue tracker to report any bugs or file feature requests.
##### Developing
PRs are welcome. To begin developing, do this:
```bash
$ git clone https://github.com/kishannareshpal/mozambique-utils.js.git
$ cd mozambique-utils/
$ npm install
# Test
$ npm test
```
`npm run build` builds the library to dist, generating three main files (and also a minified version for each one with the `*.min.js` prepended):
- `dist/mozambique-utils.cjs.js` A CommonJS bundle, suitable for use in Node.js, that requires the external dependency. This corresponds to the "main" field in package.json
- `dist/mozambique-utils.esm.js` an ES module bundle, suitable for use in other people's libraries and applications, that imports the external dependency. This corresponds to the "module" field in package.json
- `dist/mozambique-utils.js` a UMD build, suitable for use in any environment (including the browser, as a `<script>` tag), that includes the external dependency. This corresponds to the `"browser"` field in package.json
`npm run dev` builds the library, then keeps rebuilding it whenever the source files change using [`rollup.watch`](https://rollupjs.org/guide/en/#rollupwatch).
`npm test` builds the library, then tests it.
## License
MIT © [Kishan Jadav](https://kishanjadav.com)