npm package: @jaaahn/shared-utils
Description: A collection of shared utils
Author: @jaaahn
Latest version: 1.0.6

# Shared-Utils

A collection of shared utils.

Supported languages are English and German.

# Contents

-   [Installation](#installation)
-   [How to work with Date Formats](#date-formats)
-   [How to work with Date parameters](#date-parameters)
-   [How to work config Defaults](#config-defaults)
-   [Dates](#dates)
    -   [relativeDateAccurate](#relativeDateAccurate)
    -   [relativeDateLoose](#relativeDateLoose)
    -   [formatDate](#formatDate)
    -   [getWeekdayOfDate](#getweekdayofdate)
    -   [getMonthOfDate](#getMonthofdate)
-   [Strings](#strings)
    -   [leftPad](#leftPad)
-   [State Listeners](#state-listeners)
    -   [onAppChangesVisibility](#onappchangesvisibility)
-   [Lifecycle](#lifecycle)
    -   [wait](#wait)
-   [License](#license)

# Installation

`npm install @jaaahn/shared-utils`

Import all utils bundled under one object:

```js
import * as utils from "@jaaahn/shared-utils";
```

# Date formats

Sometimes a utility function takes a `dateFormat` argument. This is a string like: `YYYY-MM-DD`. The symbols are later replaced by actual values.
These symbols are available:

-   YYYY => the date's year
-   MM => month
-   DD => date
-   hh => hours
-   mm => minutes
-   ss => seconds
-   ms => milliseconds

# Date parameters

Often a date input is required. This date can be passed as a JS Date, a valid date string JavaScript can interpret or as a number representing the milliseconds counting up from 1th Jan, 1970. These input dates are in the following reference only marked as the `date` data type.

# Config Defaults

Some utilities have opional parameters, like `dateFormat`s or the `lang` parameter. These have default values that can be overwritten when calling the function (by specifying the parameters) or globally through the `defaults` object.

### Changing defaults

```js
// Import the library
import * as utils from "@jaaahn/shared-utils";

// Change a default
utils.defaults.dateFormat = "DD-MM-YYYY";
```

### Available settings and their values

```js
{
    dateFormat: "DD.MM.YYYY",
    dateTimeFormat: "DD.MM.YYYY, hh:mm",
    lang: "EN",
}
```

# Dates

## relativeDateAccurate

Output a relative representation of the difference between now and an input date. Will always try to give a accurate description, even opting to show a full date with timestamp.

`relativeDateAccurate(input: date, [lang: string], [dateFormat: string]) : string`

_input : date_  
The date that should be formated. Can either be a JS date or a correct date string.

_lang? : string ="EN"_  
The language of the output.

_dateFormat? : string ="DD.MM.YYYY"_  
Format of the output.  
[See how to provide these formats](#date-formats)

## relativeDateLoose

Output a relative representation of the difference between now and an input date.

`relativeDateLoose(input: date, [lang: string]) : string`

_input : date_  
The date that should be formated. Can either be a JS date or a correct date string.

_lang? : string ="EN"_  
The language of the output.

## formatDate

Formats a date according to the passed formatting rules.

`formatDate(input: date, [dateTimeFormat: string]) : string`

_input : date_  
The date that should be formated. Can either be a JS date or a correct date string.

_dateTimeFormat? : string ="DD.MM.YYYY, hh:mm"_  
Format of the output.  
[See how to provide these formats](#date-formats)

## getWeekdayOfDate

Takes a JS Date and returns the name of the weekday.

`getWeekdayOfDate(input: date, [lang: string]) : string`

_input : date_  
The date of which the weekday should be extracted.

_lang? : string ="EN"_  
The language of the output.

## getMonthOfDate

Takes a JS Date and returns the name of the month.

`getMonthOfDate(input: date, [lang: string]) : string`

_input : date_  
The date of which the month should be extracted.

_lang? : string ="EN"_  
The language of the output.

# Strings

## leftPad

Appends a filler character if necesarry, e.g. 7 with filler "0" => "007"
E.g. `7` gets turned into `"007"`, if `fillUpTo = 3`.

`leftPad(input: number, [fillUpTo: number], [filler: string]) : string`

_input : number_  
The input number to modify.

_fillUpTo? : number =2_  
The amount of digits to fill up. E.g. `7` gets turned into `"007"`, if `fillUpTo = 3`.

_filler? : string ="0"_
Character used to fill up input

# State Listeners

## onAppChangesVisibility

Fires a callback if the app goes into foreground (or background).

`onAppChangesVisibility(reactToState : string, callback: function) : function`

_reactToState : string_  
Must be "foreground" or "background". If this state is activated, the callback will be fired.

_callback : function_  
Callback that should be fired if app changes visibility to the specified state.

_Returns: function_  
When called, the event listener is removed. Use for example when the page unloads, to avoid two event listeners if the page is reloaded.

# Lifecycle

# wait

A promise based wait function, that sets a timeout and resolves if the timout fires.
Most useful with async/await.

`wait(ms : number) : promise`

_ms : number_
Time to wait in milliseconds

# License

[MIT License](LICENSE)  
Copyright (c) 2021 Jaaahn