@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

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 🚀

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
  • static
    • .parse(date, [format]) ⇒ Date
  • inner
    • ~Date
      • .convert(timezone) ⇒ Date
      • .diff(inputDate, [unit]) ⇒ number
      • .format([template]) ⇒ string
      • .addDays(days) ⇒ Date
      • .addMonths(months) ⇒ Date
      • .addYears(years) ⇒ Date
      • .quarter([start]) ⇒ number
      • .fiscal([start]) ⇒ Object

date.parse(date, [format]) ⇒ Date

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 date
Returns: Date - parsed date object

| Param | Type | Default | Description | | --- | --- | --- | --- | | date | string | | Date as a string | | [format] | string | "YYYY-MM-DD" | Format of the date string |

Example

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

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 date
Example

new Date().addDays(-1).convert('Asia/Colombo').format('YYYY/MM/DD')

• ~Date
  • .convert(timezone) ⇒ Date
  • .diff(inputDate, [unit]) ⇒ number
  • .format([template]) ⇒ string
  • .addDays(days) ⇒ Date
  • .addMonths(months) ⇒ Date
  • .addYears(years) ⇒ Date
  • .quarter([start]) ⇒ number
  • .fiscal([start]) ⇒ Object

date.convert(timezone) ⇒ Date

Extension method for Date object to convert to given timezone.

Kind: instance method of Date
Returns: Date - timezone Converted Date object

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

Example

Date().convert('Asia/Colombo')   // 2022-10-10T08:24:32.186Z

date.diff(inputDate, [unit]) ⇒ number

Extension method for Date object to calculate difference between 2 given dates.

Kind: instance method of Date
Returns: number - 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 | object | string | | Date object or string with a valid date (e.g. ‘2022-08-13') | | [unit] | string | "days" | 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

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

date.format([template]) ⇒ string

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 Date
Returns: string - formatted Date as a string

| Param | Type | Default | Description | | --- | --- | --- | --- | | [template] | string | "YYYY-MM-DD" | Template of date format |

Example

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"

date.addDays(days) ⇒ Date

Extension method to add/deduct number of days from a Date object.

Kind: instance method of Date
Returns: Date - new Date object with calculations applied

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

Example

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

date.addMonths(months) ⇒ Date

Extension method to add/deduct number of months from a Date object.

Kind: instance method of Date
Returns: Date - new Date object with calculations applied

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

Example

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

date.addYears(years) ⇒ Date

Extension method to add/deduct number of years from a Date object.

Kind: instance method of Date
Returns: Date - new Date object with calculations applied

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

Example

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

date.quarter([start]) ⇒ number

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 Date
Returns: number - quarter the current Date object belongs to

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

Example

new Date("2022-10-10").quarter()           // 4
new Date("2022-10-10").quarter(8)          // 1

date.fiscal([start]) ⇒ Object

Extension method to get financial year/period/quarter information.

Kind: instance method of Date
Returns: Object - fiscal period information

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

Example

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