@pinojs/dateformat

This packages is a reimplementation of the original dateformat. It focuses on performance and simplicity, while maintaining compatibility with the original API.

This package provides a DateFormat class that can be used to format dates in various ways. It supports a wide range of formatting options, including custom masks and named formats. While this package provides a dateformat function for convenience, it is recommended to use the DateFormat class directly for better performance and flexibility. While the dateformat function parses the mask-string on every call, the DateFormat class allows you to create a reusable instance with a pre-parsed mask. This can significantly improve performance when formatting dates multiple times with the same mask.

Usage

dateformat(mask, date, utc, gmt)

The dateformat function is a convenience function that allows you to format a date using a mask string. It accepts the following parameters:

• mask (string): The format mask to use for formatting the date.
• date (Date | number): The date to format. If a number is provided, it is treated as a timestamp.
• utc (boolean, optional): If true, the date is formatted in UTC. Defaults to false.
• gmt (boolean, optional): If true, the date is formatted in GMT. Defaults to false.

Example:

import { dateformat } from '@pinojs/dateformat';
const formattedDate = dateformat('yyyy-mm-dd HH:MM:ss', new Date(0));
console.log(formattedDate); // Outputs: "1970-01-01 00:00:00"

DateFormat(mask, mode)

The DateFormat class allows you to create a reusable date formatter instance with a pre-parsed mask.

It accepts the following parameters:

• mask (string|function): The format mask to use for formatting the date.
• mode (string, optional): The mode to use for formatting. Can be either 'UTC' or 'GMT'. Defaults to 'GMT'.

If the mask is a string, it is tokenized and compiled into a function for efficient date formatting. If the mask is a function, it is used directly for formatting dates.

The mask function should accept a Date object and return a formatted string. The this context of the function will be set to the DateFormat instance, allowing you to access instance methods.

Example:

With a string as mask:

import { DateFormat } from '@pinojs/dateformat';
const dateFormatter = new DateFormat('yyyy-mm-dd HH:MM:ss');
const formattedDate = dateFormatter.format(new Date(0));
console.log(formattedDate); // Outputs: "1970-01-01 00:00:00"

With a function as mask:

import { DateFormat } from '@pinojs/dateformat';
const dateFormatter = new DateFormat((date) => {
  return `${this.yyyy(date)}-${this.mm(date)}-${this.dd(date)} ${this.HH(date)}:${this.MM(date)}:${this.ss(date)}`;
});
const formattedDate = dateFormatter.format(new Date(0));
console.log(formattedDate); // Outputs: "1970-01-01 00:00:00"

Tokens

Token	Description
d	Day of the month as digits; no leading zero for single-digit days.
dd	Day of the month as digits; leading zero for single-digit days.
ddd	Day of the week as a three-letter abbreviation.
DDD	"Ysd", "Tdy" or "Tmw" if date lies within these three days. Else fall back to ddd.
dddd	Day of the week as its full name.
DDDD	"Yesterday", "Today" or "Tomorrow" if date lies within these three days. Else fall back to dddd.
m	Month as digits; no leading zero for single-digit months.
mm	Month as digits; leading zero for single-digit months.
mmm	Month as a three-letter abbreviation.
mmmm	Month as its full name.
yy	Year as last two digits; leading zero for years less than 10.
yyyy	Year represented by four digits.
h	Hours; no leading zero for single-digit hours (12-hour clock).
hh	Hours; leading zero for single-digit hours (12-hour clock).
H	Hours; no leading zero for single-digit hours (24-hour clock).
HH	Hours; leading zero for single-digit hours (24-hour clock).
M	Minutes; no leading zero for single-digit minutes.
MM	Minutes; leading zero for single-digit minutes.
N	ISO 8601 numeric representation of the day of the week.
o	GMT/UTC timezone offset, e.g. -0500 or +0230.
p	GMT/UTC timezone offset, e.g. -05:00 or +02:30.
s	Seconds; no leading zero for single-digit seconds.
ss	Seconds; leading zero for single-digit seconds.
S	The date's ordinal suffix (st, nd, rd, or th). Works well with d.
l	Milliseconds; gives 3 digits.
L	Milliseconds; gives 2 digits.
t	Lowercase, single-character time marker string: a or p.
tt	Lowercase, two-character time marker string: am or pm.
T	Uppercase, single-character time marker string: A or P.
TT	Uppercase, two-character time marker string: AM or PM.
W	ISO 8601 week number of the year, e.g. 4, 42
WW	ISO 8601 week number of the year, leading zero for single-digit, e.g. 04, 42
Z	The GMT-Offset is, e.g. GMT-0500, or if it is GMT-0000 it will be return UTC
'...', "..."	Literal character sequence. Surrounding quotes are removed.
UTC:	Must be the first four characters of the mask. Converts the date from local time to UTC/GMT/Zulu time before applying the mask. The "UTC:" prefix is removed.

Named Formats

Name	Mask	Example
default	ddd mmm dd yyyy HH:MM:ss	Sat Jun 09 2007 17:46:21
shortDate	m/d/yy	6/9/07
paddedShortDate	mm/dd/yyyy	06/09/2007
mediumDate	mmm d, yyyy	Jun 9, 2007
longDate	mmmm d, yyyy	June 9, 2007
fullDate	dddd, mmmm d, yyyy	Saturday, June 9, 2007
shortTime	h:MM TT	5:46 PM
mediumTime	h:MM:ss TT	5:46:21 PM
longTime	h:MM:ss TT Z	5:46:21 PM EST
isoDate	yyyy-mm-dd	2007-06-09
isoTime	HH:MM:ss	17:46:21
isoDateTime	yyyy-mm-dd'T'HH:MM:sso	2007-06-09T17:46:21+0700
isoUtcDateTime	UTC:yyyy-mm-dd'T'HH:MM:ss'Z'	2007-06-09T22:46:21Z