@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