@theredhead/dateformat

• @theredhead/dateformat
  • Purpose
  • Features
  • Caveats
  • Usage
    • the dateFormat function
    • The dateHelper instance
    • the DateHelper class

Purpose

Make working with the built-in Date class a little bit more tolerable.

Features

• Source code freely available: https://github.com/theredhead/dateformat
• Provides a dateFormat(date: Date, formatString: string): string function that takes a format just like PHP's date_format function.
• Format string placeholders:

This is almost straight from the php documentation

Char	Description
d	Day of the month, 2 digits with leading zeros
D	A textual representation of a day, three letters
j	Day of the month without leading zeros
l	A full textual representation of the day of the week
N	ISO-8601 numeric representation of the day of the week
S	English ordinal suffix for the day of the month, 2 characters
w	Numeric representation of the day of the week
z	The day of the year (starting from 0)
W	ISO-8601 week number of year, weeks starting on Monday
F	A full textual representation of a month, such as January or March
m	Numeric representation of a month, with leading zeros
M	A short textual representation of a month, three letters
n	Numeric representation of a month, without leading zeros
t	Number of days in the given month
L	Whether it's a leap year
o	ISO-8601 week-numbering year. This has the same value as Y, except that if the ISO week number (W) belongs to the previous or next year, that year is used instead
Y	A full numeric representation of a year, 4 digits
y	A two digit representation of a year
a	Lowercase Ante meridiem and Post meridiem
A	Uppercase Ante meridiem and Post meridiem
B	Swatch Internet time
g	12-hour format of an hour without leading zeros
G	24-hour format of an hour without leading zeros
h	12-hour format of an hour with leading zeros
H	24-hour format of an hour with leading zeros
i	Minutes with leading zeros
s	Seconds with leading zeros
u	Microseconds
v	Milliseconds
O	Difference to Greenwich time (GMT) without colon between hours and minutes
P	Difference to Greenwich time (GMT) with colon between hours and minutes
p	The same as P, but returns Z instead of +00:00
Z	Timezone offset in seconds. The offset for timezones west of UTC is always negative, and for those east of UTC is always positive.
c	ISO 8601 date
r	RFC 2822 formatted date ("Thu, 21 Dec 2000 16:01:07 +0200")
U	Seconds since the Unix Epoch (January 1 1970 00:00:00 GMT)

Caveats

My implementation is almost, but not quite entirely, complete. I am still missing a few options that I don't really want to support as it would involve tracking a bunch of data:

Char	Description	note
e	Timezone identifier	NOT IMPLEMENTED
I	Whether or not the date is in daylight saving time	NOT IMPLEMENTED
T	Timezone abbreviation	NOT IMPLEMENTED

Furthermore, the unittests are fairly basic (as of 2021-03-13)

Usage

There are several ways you could use this package:

the dateFormat function

If all you need is a quick formatting of a date here and there, you could get away with just importing the dateFormat funtion and forgetting about everything else.

The function expects two arguments; a Date instance and a string witht he required formatting characters as described above.

  import { dateFormat } from '@theredhead/dateformat';

  const date = new Date();
  console.log("It is " + dateFormat(date, "H:i:s")); // It is 18:43:51

The dateHelper instance

If you might need to do some more Date inspection, you may want to use the same dateHelper instance that the exported function uses

  import { dateHelper } from '@theredhead/dateformat';

  function schedule(dueDate, task) {
    if (! dateHelper.isDate(dueDate)) {
      throw new Error('Expected a Date.');
    }
    // ...
  }
  console.log("It is " + dateFormat(date, "H:i:s")); // It is 18:43:51

the DateHelper class

If you just want to break stuff, import the DateHelper class. Maybe extend it or bend it to your will in some novel way I haven't thought of yet.