@cstan/simple-date

simple-date

An ES6 module that deals only with dates, no time or time zone considerations.

This module is a function that returns an object with numerous methods that we have found very useful in some of our projects. Hopefully you will also find them useful and easy to use. Because it is an export default module you can use any name for the imported function, we typically use sDate but use what suits you.

Installation:

npm install @cstan/simple-date

Use:

import sDate from '@cstan/simple-date';

const myDate = sDate("2018-05-22");

console.log(`Three months later: ${myDate.plus(3, "months").display()}`);
// Three months later: 08/22/2018

Arguments for sDate():

To create a simple-date object you have several argument options:
  - A Javascript Date object
  - The ISO date standard as shown in the above example, "yyyy-mm-dd"
  - A USA standard date format, "mm?dd?yyyy" where the ? can be any non-digit character
  - A USA string without dividers, "mmddyyyy"
  - No argument which will create a date object with the current date

Display methods:

  - myDate.display() returns string withUSA standard date format "mm/dd/yyyy"
  - myDate.display with argument:
    myDate.display(".") returns "mm.dd.yyyy"
    myDate.display("-") returns "mm-dd-yyyy"
  - myDate.isoDate() returns standard ISO date "yyyy-mm-dd"
  - myDate.genDate() returns common genealogical date format "dd Mon yyyy"

Getting date parts methods:

By getting date parts and assembling them into a custom string you can create your own date format.

  - myDate.getWeekDay() returns name of day, ie. "Thursday"
  - myDate.getDay() returns two digit string for day of the month, ie. "08"
  - myDate.dd() same as previous method
  - myDate.getMo() returns two digit string for month, ie. "01" (January)
  - myDate.mm() same as previous method
  - myDate.getMON() returns three upper case character for month, ie. "JUL"
  - myDate.getMonth() returns full name of month, ie. "October"
  - myDate.getYear() returns four digit string for year, ie. "1998"
  - mdDate.yyyy() same as previous method

Example custom date:

import sDate from '@cstan/simple-date';

const someDate = "2021-09-17";
const d = sDate(someDate);

const customDisplay = function(do) { // do is a date object produced by sDate
  return do.getWeekDay + ", " + do.getMonth() + " " + do.dd() + ", " + dt.yyyy();
}

console.log(`Some day: ${customDisplay(d)});
// Some day: Friday, September 17, 2021

Getting ages or differences between two dates:

The arguments for the age generating methods can be any argument usable by the simple-date function including no argument for todays date (See the Arguments section above). Internally it is used to create a new simple-date object. For the following examples we will use "1963-05-27" but other formats would work.

Assume we start with:

  startDate = sDate("1963-05-27");

Methods:

You can think of usage this way: startDate.ageInDays as of ("1963-07-19")

  - startDate.ageInDays("1963-07-19") // returns 53
  - startDate.ageInWeeks("1963-07-19") // returns 7
  - startDate.ageInYears() // will use current date, for example if we assume today is "1985-02-12"
      // returns 21
  - startDate.ageInDecades("1993-04-23") // returns 2 (about 3 months short of 3 decades)

Math methods, plus() and minus()

Arguments: These methods take two arguments.

The first is an integer that expresses the quantity that will be added or subtracted from the internal date.

The second argument is a string that designates the units to be added or subtracted. Valid units include:
  "days"
  "weeks"
  "months"
  "years"
  "decades"
  "centuries"

Returns:

All math methods return a new simple-date object with the calculated date as its internal date which allows chaining as demonstrated below.

Methods:

  myDate = sDate("1950-07-01")

  - myDate.plus(3, "days").isoDate() // returns "1950-07-04"
  - myDate.plus(2, "weeks").display() // returns "07/15/1950"
  - myDate.plus(4, "months").display("-") // returns "11-01-1950"
  - myDate.plus(5, "years").isoDate() // returns "1955-07-01"
  - myDate.plus(3, "decades").display(".") // returns "07.01.1980"
  - myDate.plus(1, "centuries").isoDate() // returns "2050-07-01"

While using the 'minus' method do NOT use negative numbers. Also note other chained methods used in the examples.

  - myDate.minus(5, "days").getWeekDay() // returns "Monday"
  - sDate("1950-07-01").minus(2, "weeks").dd() // returns 17 (Note we used sDate directly here)
  - myDate.minus(11, "months").display() // returns "08/01/1949"
  - myDate.minus(23, "years").display() // returns "07/01/1927"
  - myDate.minus(4, "decades").display() // returns "07/01/1910"
  - myDate.minus(7, "centuries").display() // returns "07/01/1250"

Methods to access internal numbers

These methods are not generally used but might be useful for special situations.

The getDayCount method provides the count of days from zero point (midnight before 01/01/0001) to the internal date. The day count for 01/01/0001 is 1 and the day count for 08/01/1949 is 711,705.

  - sDate("08/01/1949").getDayCount() // returns 711705

The getDoy method provides the day of the year. The day of the year for 01/01/1949 is 1 and the day count for 08/01/1949 is 213.

  - sDate("08/01/1949").getDoy() // returns 213

The getDow method provides the numeric day of the week where Sunday = 0, Monday = 1, etc.

  - sDate("08/01/1949").getDow() // returns 1