npm package: @novigi/date
Description: Really simple and lightweight Javascript date parsing, manipulating and formatting util 🚀
Author: Novigi
Latest version: 1.0.0-2

![npm (scoped)](https://img.shields.io/npm/v/@novigi/date) ![NPM](https://img.shields.io/npm/l/@novigi/date) ![Statements](https://img.shields.io/badge/statements-100%25-brightgreen.svg?style=flat) ![Branches](https://img.shields.io/badge/branches-98.98%25-brightgreen.svg?style=flat) ![Functions](https://img.shields.io/badge/functions-100%25-brightgreen.svg?style=flat) ![Lines](https://img.shields.io/badge/lines-100%25-brightgreen.svg?style=flat)
# @novigi/date

Really simple and lightweight Javascript date parsing, manipulating and formatting util 🚀

## 🐿 Features

- Chainable and immutable API
- Date/time parsing and formatting using standard tokens → `YYYY`, `MM` .etc
- Financial year calculations

## 📦 Getting Started

1. Install the dependency
```
npm install @novigi/date
```

2. Import the library
```
const lib = require('@novigi/date');
```

## 📖 Documentation

<a name="module_date"></a>

## date
This library contains methods that allow user to parse or format Date objects with year, month, day, hour, minute,
second and milisecond using either local time or UTC (universal, or GMT) time. Timezone converter is capable of offetting the
time and change the timezone of a `Date` object.

This gudieline is about the formats and exmaples that can follow for Javascript date parsing, conversion and formatting util 🚀

```js
const { lib } = require('@novigi/date');
lib.parse('2022.21.05', 'YYYY.DD.MM').addDays(3).convert('Asia/Colombo').format('YYYY MM DD') //2022 05 24
```

Chainable + immutable methods! ☝


* [date](#module_date)
    * _static_
        * [.parse(date, [format])](#module_date.parse) ⇒ <code>Date</code>
    * _inner_
        * [~Date](#external_Date)
            * [.convert(timezone)](#external_Date+convert) ⇒ <code>Date</code>
            * [.diff(inputDate, [unit])](#external_Date+diff) ⇒ <code>number</code>
            * [.format([template])](#external_Date+format) ⇒ <code>string</code>
            * [.addDays(days)](#external_Date+addDays) ⇒ <code>Date</code>
            * [.addMonths(months)](#external_Date+addMonths) ⇒ <code>Date</code>
            * [.addYears(years)](#external_Date+addYears) ⇒ <code>Date</code>
            * [.quarter([start])](#external_Date+quarter) ⇒ <code>number</code>
            * [.fiscal([start])](#external_Date+fiscal) ⇒ <code>Object</code>

<a name="module_date.parse"></a>

### date.parse(date, [format]) ⇒ <code>Date</code>
Creates a Date object from date time string and known format.
`parse` method will use the format to parse the date time string and constructs a `Date` object. If the format is invalid
or unable to process the input date-time string with, it fallbacks to the javascript default date time parsing strategy.

Available formatting options are as follows;

| Input       | Example             | Description |
| ----------- | ------------------- | ----------- |
| `YYYY`      | `2014`              | 4 or 2 digit year. Note: Only 4 digit can be parsed on `strict` mode |
| `YY`        | `14`                | 2 digit year |
| `M`         | `1..12`             | Month number |
| `MM`        | `01..12`            | Month number (numbers with leading 0) |
| `MMM`       | `Jan..Dec`          | Month name (Short) |
| `MMMM`      | `January..December` | Month name (full) |
| `D`         | `1..31`             | Day of month |
| `DD`        | `01..31`            | Day of month (numbers with leading 0) |
| `H`         | `0..23`             | Hours (24 hour time) |
| `HH`        | `00..23`            | Hours (24 hour time, leading 0) |
| `h`         | `1..12`             | Hours (12 hour time used with `a A`.) |
| `hh`        | `01..12`            | Hours (12 hour time used with `a A`., leading 0) |
| `a`         | `am pm`             | Post or ante meridiem (Note the one character `a p` are also considered valid) |
| `A`         | `AM PM`             | Post or ante meridiem (Note the one character `A P` are also considered valid) |
| `m`         | `0..59`             | Minutes |
| `mm`        | `00..59`            | Minutes (numbers with leading 0) |
| `s`         | `0..59`             | Seconds |
| `ss`        | `00..59`            | Seconds (numbers with leading 0) |
| `SSS`       | `000..999`          | Milliseconds (numbers with leading 0) |
| `Z`         | `+05:30`            | Offset from UTC as `+-HH:mm`, `+-HHmm`, or `Z` |

**Kind**: static method of [<code>date</code>](#module_date)  
**Returns**: <code>Date</code> - parsed date object  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| date | <code>string</code> |  | Date as a string |
| [format] | <code>string</code> | <code>&quot;YYYY-MM-DD&quot;</code> | Format of the date string |

**Example**  
```js
lib.parse('2022-08-13')                                                // 2022-08-13T00:00:00.000Z
lib.parse('2022-08-13T01:21:23', 'YYYY-MM-DD')                         // 2022-08-13T00:00:00.000Z
lib.parse("2022-08-13T00:10:00.000+05:30", "YYYY-MM-DDTHH:mm:ss.SSSZ") // 2022-08-12T18:40:00.000Z
```
<a name="external_Date"></a>

### date~Date
Extension methods for built-in Date object. Most of these methods are returning a new Date object so the API is
immutable and chainable.

**Kind**: inner external of [<code>date</code>](#module_date)  
**Example**  
```js
new Date().addDays(-1).convert('Asia/Colombo').format('YYYY/MM/DD')
```

* [~Date](#external_Date)
    * [.convert(timezone)](#external_Date+convert) ⇒ <code>Date</code>
    * [.diff(inputDate, [unit])](#external_Date+diff) ⇒ <code>number</code>
    * [.format([template])](#external_Date+format) ⇒ <code>string</code>
    * [.addDays(days)](#external_Date+addDays) ⇒ <code>Date</code>
    * [.addMonths(months)](#external_Date+addMonths) ⇒ <code>Date</code>
    * [.addYears(years)](#external_Date+addYears) ⇒ <code>Date</code>
    * [.quarter([start])](#external_Date+quarter) ⇒ <code>number</code>
    * [.fiscal([start])](#external_Date+fiscal) ⇒ <code>Object</code>

<a name="external_Date+convert"></a>

#### date.convert(timezone) ⇒ <code>Date</code>
Extension method for Date object to convert to given timezone.

**Kind**: instance method of [<code>Date</code>](#external_Date)  
**Returns**: <code>Date</code> - timezone Converted Date object  

| Param | Type | Description |
| --- | --- | --- |
| timezone | <code>string</code> | String containing standard Javascript timezone where Date should be converted to |

**Example**  
```js
Date().convert('Asia/Colombo')   // 2022-10-10T08:24:32.186Z
```
<a name="external_Date+diff"></a>

#### date.diff(inputDate, [unit]) ⇒ <code>number</code>
Extension method for Date object to calculate difference between 2 given dates.

**Kind**: instance method of [<code>Date</code>](#external_Date)  
**Returns**: <code>number</code> - number of milliseconds/ seconds/ minutes/ hours/ days/ weeks/ months or years between the given two dates excluding the end date  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| inputDate | <code>object</code> \| <code>string</code> |  | Date object or string with a valid date (e.g. ‘2022-08-13') |
| [unit] | <code>string</code> | <code>&quot;days&quot;</code> | An optional argument which allows you to specify whether you need the difference in milliseconds/ seconds/ minutes/ hours/ days/ weeks/ months or years. By default Output is in days |

**Example**  
```js
new Date('2022-12-30').diff('2022-12-31')                     // 1
new Date('2022-12-31').diff('2021/12/31', 'years')            // 1
new Date('2022-12-31').diff(new Date('2022-01-01'), 'months') // 11
```
<a name="external_Date+format"></a>

#### date.format([template]) ⇒ <code>string</code>
Lightweight and fast method to format a date as a string.

Supported parsing tokens for the formatting. To escape characters in format strings, you can wrap the characters in square brackets.

| Input  | Example          | Description                       |
| ------ | ---------------- | --------------------------------- |
| `YY`   | 01               | Two-digit year                    |
| `YYYY` | 2001             | Four-digit year                   |
| `M`    | 1-12             | Month, beginning at 1             |
| `MM`   | 01-12            | Month, 2-digits                   |
| `MMM`  | Jan-Dec          | The abbreviated month name        |
| `MMMM` | January-December | The full month name               |
| `D`    | 1-31             | Day of month                      |
| `DD`   | 01-31            | Day of month, 2-digits            |
| `d`    | 0-6              | Day of Week, 0 indexed            |
| `dd`   | Su Mo ... Fr Sa  | Day of Week, 2 letters            |
| `ddd`  | Sun ... Fri Sat  | Day of Week, 3 letters            |
| `dddd` | Sunday Monday..  | Day of Week, full                 |
| `H`    | 0-23             | Hours                             |
| `HH`   | 00-23            | Hours, 2-digits                   |
| `h`    | 1-12             | Hours, 12-hour clock              |
| `hh`   | 01-12            | Hours, 12-hour clock, 2-digits    |
| `a`    | am pm            | Post or ante meridiem, lower-case |
| `A`    | AM PM            | Post or ante meridiem, upper-case |
| `m`    | 0-59             | Minutes                           |
| `mm`   | 00-59            | Minutes, 2-digits                 |
| `s`    | 0-59             | Seconds                           |
| `ss`   | 00-59            | Seconds, 2-digits                 |
| `S`    | 0-9              | Hundreds of milliseconds, 1-digit |
| `SSS`  | 000-999          | Milliseconds, 3-digits            |
| `Z`    | +05:30           | Offset from UTC                   |
| `ZZ`   | +0530            | Compact offset from UTC, 2-digits |

**Kind**: instance method of [<code>Date</code>](#external_Date)  
**Returns**: <code>string</code> - formatted Date as a string  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| [template] | <code>string</code> | <code>&quot;YYYY-MM-DD&quot;</code> | Template of date format |

**Example**  
```js
new Date().format()                                 // "2022-10-10"
new Date().format('YYYY-MM-DD')                     // "2022-10-10"
new Date().format('dddd, MMMM Do YYYY, h:mm:ss a')  // "Sunday, February 14th 2010, 3:25:50 pm"
new Date().format('ddd, hA')                        // "Sun, 3PM"
new Date().format('[Today is] dddd')                // "Today is Sunday"
```
<a name="external_Date+addDays"></a>

#### date.addDays(days) ⇒ <code>Date</code>
Extension method to add/deduct number of days from a Date object.

**Kind**: instance method of [<code>Date</code>](#external_Date)  
**Returns**: <code>Date</code> - new Date object with calculations applied  

| Param | Type | Description |
| --- | --- | --- |
| days | <code>number</code> | Number of days to add to the Date. Use minus to deduct days |

**Example**  
```js
new Date("2022-10-10").addDays(1)           // 2022-10-11T00:00:00.000Z
new Date("2022-10-10").addDays(-1)          // 2022-10-09T00:00:00.000Z
```
<a name="external_Date+addMonths"></a>

#### date.addMonths(months) ⇒ <code>Date</code>
Extension method to add/deduct number of months from a Date object.

**Kind**: instance method of [<code>Date</code>](#external_Date)  
**Returns**: <code>Date</code> - new Date object with calculations applied  

| Param | Type | Description |
| --- | --- | --- |
| months | <code>number</code> | Number of months to add to the Date. Use minus to deduct months |

**Example**  
```js
new Date("2022-10-10").addMonths(1)           // 2022-11-10T00:00:00.000Z
new Date("2022-10-10").addMonths(-1)          // 2022-09-10T00:00:00.000Z
```
<a name="external_Date+addYears"></a>

#### date.addYears(years) ⇒ <code>Date</code>
Extension method to add/deduct number of years from a Date object.

**Kind**: instance method of [<code>Date</code>](#external_Date)  
**Returns**: <code>Date</code> - new Date object with calculations applied  

| Param | Type | Description |
| --- | --- | --- |
| years | <code>number</code> | Number of years to add to the Date. Use minus to deduct years |

**Example**  
```js
new Date("2022-10-10").addYears(1)           // 2023-10-10T00:00:00.000Z
new Date("2022-10-10").addYears(-1)          // 2021-10-10T00:00:00.000Z
```
<a name="external_Date+quarter"></a>

#### date.quarter([start]) ⇒ <code>number</code>
Extension method to get quarter from a Date object. Optional parameter can be passed to
set the start of year if required (i.e., fiscal quarter calculations).

**Kind**: instance method of [<code>Date</code>](#external_Date)  
**Returns**: <code>number</code> - quarter the current Date object belongs to  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| [start] | <code>number</code> | <code>1</code> | Starting month of the year. January = 1 |

**Example**  
```js
new Date("2022-10-10").quarter()           // 4
new Date("2022-10-10").quarter(8)          // 1
```
<a name="external_Date+fiscal"></a>

#### date.fiscal([start]) ⇒ <code>Object</code>
Extension method to get financial year/period/quarter information.

**Kind**: instance method of [<code>Date</code>](#external_Date)  
**Returns**: <code>Object</code> - fiscal period information  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| [start] | <code>number</code> | <code>1</code> | Starting month of the year. January = 1 |

**Example**  
```js
new Date("2022-08-10").fiscal()           // { year: 2022, period: 8, quarter: 3 }
new Date("2022-08-10").fiscal(7)          // { year: 2023, period: 2, quarter: 1 }
```

_This is an auto generated file. Please don't make changes manually_