# FrontUtils

> This is a package for handling payping front's common utils.

## Install

yarn:

```bash
yarn add @payping/utils
```

npm:

```bash
npm install @payping/utils
```

## Description

The utilities in this package are separated into 4 parts:

1. **root** (`@payping/utils`):

|       Exports       | Description                          |
| :-----------------: | :----------------------------------- |
| applyTaxAndDiscount | setting tax and discount for invoice |
|     generateQr      | function for creating a qr code      |

2. **dateUtils** (`@payping/utils/dateUtils`):

|    Exports    | Description                                           |
| :-----------: | :---------------------------------------------------- |
|   toJalali    | functions for converting `date/time` to jalali        |
|     toUtc     | functions for converting `date/time` to utc           |
|   jalaliNow   | functions for getting current jalali `date/time`      |
|    utcNow     | functions for getting current utc `date/time`         |
|  dateFormats  | usable date formats for using in PayPing applications |
| isBeforeToday | if given `date/time` is before beginning of today     |
| SDKDateObject | type of PayPing date objects                          |

3. **fetchQueue** (`@payping/utils/fetchQueue`):

These functions are used in `desktop` and `mobile` applications for queueing api requests while device is offline and handling them after becoming online.

|      Exports       | Description |
| :----------------: | :---------- |
|     QueuePool      |             |
|  initAppQueuePool  |             |
|     queueNames     |             |
| fetchQueueReducer  |             |
|  updateQueueList   |             |
| updateFetchingKeys |             |

4. **gitHooks** utils. these utils are not used in any code, just used by husky in package.json files for validating code changes.

5. **hooks** (`@payping/utils/hooks`):

|           Exports           | Description                                                                       |
| :-------------------------: | :-------------------------------------------------------------------------------- |
|      useMessagedAsync       | react-use's `useAsync` hook combined with progress bar and message                |
|     useMessagedAsyncFn      | react-use's `useAsyncFn` hook combined with progress bar and message              |
|    useMessagedAsyncRetry    | react-use's `useAsyncRetry` hook combined with progress bar and message           |
| useRouteNameAsDocumentTitle | set document title of the page (translations should be present inside `pageTitle` |

6. **locales**: only used inside the frontutils package for setting translations.

7. **localeUtils** (`@payping/utils/localeUtils`): containing config constant & functions of i18n and:

|        Exports         | Description                                                                                    |
| :--------------------: | :--------------------------------------------------------------------------------------------- |
| adminLocaleNameSpaces  | admin dashboard namespace enum                                                                 |
|    localeNameSpaces    | dashboard namespace enum                                                                       |
| useIsolatedTranslation | useTranslation with namespace                                                                  |
|      initI18next       | initial config of i18next for admin dashboard                                                  |
|    initAdminI18next    | initial config of i18next for dashboard                                                        |
|   injectLocaleFiles    | adding locale `.json` files to i18n resources                                                  |
|         Trans          | Trans component of `react-i18next` package. do not import Trans from `react-i18next` directly. |

8. **platformConstants** (`@payping/utils/platformConstants`):

|     Exports      | Description                                        |
| :--------------: | :------------------------------------------------- |
| commonConstants  | common constant variables for all platforms        |
| desktopConstants | specific constant variables for `phone` platform   |
|  phoneConstants  | specific constant variables for `desktop` platform |
| tabletConstants  | specific constant variables for `tablet` platform  |
|   webConstants   | specific constant variables for `web` platform     |

9. **query-string** (`@payping/utils/query-string`):

|      Exports      | Description                                     |
| :---------------: | :---------------------------------------------- |
| submitQueryParams | function for modifying query params of the page |

10. **status** (`@payping/utils/status`): getting correct status of some methods.

11. **string** (`@payping/utils/string`):

|        Exports         | Description                                                                            |
| :--------------------: | :------------------------------------------------------------------------------------- |
|        addComma        | separate thousands with comma                                                          |
|      addOverflow       | add `...` at the end of long strings                                                   |
| commaMaskedInputHelper | has two methods for `mask` and `unmask` to insert or remove comma separators in number |
|    extensionMimeMap    | map file extensions to corresponding html mime type                                    |
|    getFileExtension    | get the extension from a file name                                                     |
|      getFileName       | generate a file name based on its extension                                            |
|      getFileType       | get mime type of a file name based on its extension                                    |
|       isAlphabet       | is just alphabets in the string                                                        |
|      onlyNumbers       | only allow numbers in string                                                           |
|   removeLeadingZeros   | removes zeros at the beginning of number                                               |
|     safeDeletePath     | remove path from base with perpetual heading `/` and remove tailing `/`                |
|      safeJoinPath      | concat path(s) to base, with heading `/` and without tailing `/`                       |
|        safeStr         | convert number to string and return fallback value if not convertable to string        |
|       toEnDigit        | replace `persian` digits with `english` ones                                           |
|       toFaAlpha        | convert arabic letters to persian corresponding ones                                   |
|   toRightPhoneNumber   | validate phone number                                                                  |
|     unmaskStrToNum     | convert string with comma to number type without comma                                 |

11. **validation** (`@payping/utils/validation`):

|        Exports        | Description                                    |
| :-------------------: | :--------------------------------------------- |
|      ValidEmail       | validation function for Email input            |
|   ValidMobileNumber   | validation function for MobileNumber input     |
|    ValidNationalId    | validation function for NationalId input       |
|    ValidPostalCode    | validation function for PostalCode input       |
|      ValidSheba       | validation function for Sheba input            |
|       ValidUrl        | validation function for Url input              |
| ValidUrlWithLocalhost | validation function for UrlWithLocalhost input |
| ValidLocalPhoneNumber | validation function for LocalPhoneNumber input |

## Usage

```javascript
import { generateQr } from "@payping/utils";
import { toJalali } from "@payping/utils/dateUtils";
```

### Checking changes before Publish

1. Run script for **building** package on local (`customPrepublishOnly`).
2. Output will be in a `dist` folder at the root of the project.
3. Go to the project that you want to install this package in and install it locally:
   ```shell
   yarn add ../frontutils/dist/
   ```
   > **NOTE:** If your project has submodules you need to use the `-W` option in `yarn add` command and replace the version of the package in all package.json files with this route `../frontutils/dist/`.