@novigi/date v1.0.0-2

@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;

Kind: static method of date
Returns: Date - parsed date object

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

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

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.

Kind: instance method of Date
Returns: string - formatted Date as a string

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

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

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

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

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

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