@deposits/utils
Version:
A collection of utility functions that we have found ourselves reuse across our frontend, kept in one place and documented.
224 lines (147 loc) • 6.47 kB
Markdown
# Deposits Utils
## Overview
This repository contains a documented collection of JavaScript utility functions that we frequently use across various frontend projects, centralized in one place.
---
## Installation
To install the utilities, simpy run the bash command.
```bash
npm install /utils
```
---
## List of Utility Functions
### `capitalize`
This function is used to capitalize the first character of a string.
```typescript
function capitalize(str: string, lowerOtherCharacters: bool): string {}
```
**Arguments**
- `str` - The string being capitalized
- `lowerOtherCharacters` - This boolean flag determines whether the function should convert all characters after the first character to lower case or leave them as they are
**Example**
```javascript
import { capitalize } from "@deposits/utils";
capitalize("something"); // Something
capitalize("somEthing"); // SomEthing
capitalize("somEthing", true); // Something
```
---
### `displayDate`
This function uses [luxon](https://moment.github.io/luxon/#/?id=luxon) under the hood to display dates in any format in UTC.
It accepts dates either as JavaScript dates, Luxon DateTime, ISO or an array of supported formats `["dd-MM-yyyy", "MM-dd-yyyy", "yyyy-MM-dd", "dd/MM/yyyy", "MM/dd/yyyy", "yyyy/MM/dd", "dd/MM/yyyy"]` and displays them in the supplied format.
```typescript
function displayDate(
date: string | Date | DateTime,
toFormat: string = "LLL dd, yyyy",
fromFormat: string
): string {}
```
**Arguments**
- `date` - A string or object representing the date to be displayed
- `toFormat` - The format to display the date in. The default is `"LLL dd, yyyy"`
- `fromFormat` - A string specifying the format the date string (the first argument) is in to aid with the parsing
**Example**
```javascript
import { displayDate } from "@deposits/utils";
displayDate(new Date()); // Oct 20, 2024
displayDate("2024-11-10"); // Nov 11, 2024
displayDate("2024/11/10"); // Nov 11, 2024
displayDate("10-11-2024"); // Nov 11, 2024
displayDate(new Date(), "MMM dd, y, hh:mma"); // Oct 20, 2024 05:21AM
displayDate("2024-11-10", undefined, "yyyy-dd-MM"); // Oct 11, 2024
displayDate("2024-11-10", "MMM dd, y, hh:mma", "yyyy-dd-MM"); // Oct 11, 2024 12:00AM
```
**Note**
This function uses the tokens defined for luxon for it's formatting. See more [here](https://moment.github.io/luxon/#/formatting?id=table-of-tokens)
---
### `mask`
This function can be used to mask a string. It also supports masking emails to show the domain part of the email while masking the first part.
```typescript
function mask(string: string, maskChar: string = "*", unmaskedChars: number = 4): string {}
```
**Arguments**
- `string` - The string to be masked
- `maskChar` - The character the of the masked strings. Defaults to `*`
- `unmaskedChars` - The number of characters to leave unmasked. Defaults to `4`
**Example**
```javascript
import { mask } from "@deposits/utils";
mask("somethingforyorumind"); // ****************mind
mask("eric.mcwinner@ingomoney.com"); // e************@ingomoney.com
mask("somethingforyorumind", "#"); // ################mind
mask("somethingforyorumind", undefined, 7); // *************orumind
```
---
### numberFormat
This function is used to format displayed numbers. It supports thousand separators and decimal places, as well as specifying exponents.
It works in a similar way to the built-in PHP [`number_format`](https://www.php.net/manual/en/function.number-format.php)
```typescript
function numberFormat(
number: number | string,
decimals: number,
dec_point: string = ".",
thousands_sep: string = ","
): string {}
```
**Arguments**
- `number` - The number to be formatted and displayed.
- `decimals` - The number of decimal places to be shown.
- `dec_point` - The character to be used for the decimal point. Defaults to `.`
- `thousands_sep` - The character to be used to separate thousands. Defaults to ','
**Example**
```javascript
import { numberFormat } from "@deposits/utils";
numberFormat(2000); // 2,000
numberFormat(2000, 2); // 2,000.00
numberFormat(2000, 2, ".", "."); // 2.000.00
numberFormat(2000.889, 2); // 2,000.89
```
---
### `parseDate`
This function is used to convert a formatted date string to a JavaScript date in UTC.
It tries to match the string to an array of formats: `["dd-MM-yyyy", "MM-dd-yyyy", "yyyy-MM-dd", "dd/MM/yyyy", "MM/dd/yyyy", "yyyy/MM/dd", "dd/MM/yyyy"]` if no format is provided and converts the supplied date to a JavaScript date in UTC.
It can be seen as the opposite of `displayDate`
```typescript
function parseDate(dateString: string, format: string, zone: string = "utc"): Date {}
```
**Arguments**
- `dateString` - The date string to be parsed.
- `format` - The format the date string is in. We use tokens based on luxon. You can learn more [here.](https://moment.github.io/luxon/#/formatting?id=table-of-tokens)
- `zone` - The timezone the supplied date should be converted to. It defaults to UTC.
**Example**
```javascript
import { parseDate } from "@deposits/utils";
parseDate("15-10-2024", "dd-MM-yyyy"); // 2024-10-15T00:00:00.000Z
parseDate("2024-10-15"); // 2024-10-15T00:00:00.000Z
parseDate("10/15/2024"); // 2024-10-15T00:00:00.000Z
```
---
### `sentenceCase`
This function is similar to `capitalize` but what it does is run `capitalize` on every word in a sentence, to convert the string to sentence case.
```typescript
function sentenceCase(str: string, lowerOtherCharacters: bool): string {}
```
**Arguments**
- `str` - The string being capitalized
- `lowerOtherCharacters` - This boolean flag determines whether the function should convert all characters after the first character to lower case or leave them as they are
**Example**
```javascript
import { sentenceCase } from "@deposits/utils";
sentenceCase("The quick brown fox"); // The Quick Brown Fox
sentenceCase("The quIck brown Fox", true); // The Quick Brown Fox
```
---
### `sentencify`
This function is used to convert a string to a sentence based on delimiter.
e.g "deposits_is_awesome" becomes "deposits is awesome".
```typescript
function sentencify(string: string, delimiter: string = "_"): string {}
```
**Arguments**
- `string` - The string to convert to a sentence.
- `delimiter` - The token to convert to spaces.
**Example**
```javascript
import { sentencify } from "@deposits/utils";
sentencify("in_progress"); // in progress
sentencify("in-progress", "-"); // in progress
```