thdoan/strftime

A JavaScript port of strftime().

strftime()

A JavaScript port of strftime(), a function to format the date and time.

Supported conversion specifications:

Sequence	Description	Example
%a	Abbreviated name of the day of the week.	Fri
%A	Full name of the day of the week.	Friday
%b	Abbreviated month name.	Apr
%B	Full month name.	April
%c	UTC date and time representation for the current locale.	Sat 02 Apr 2022 00:15:00 GMT
%C	Century number (year/100) as a 2-digit integer.	20
%d	Day of the month as a decimal number (range 01 to 31).	01
%e	Day of the month as a decimal number (range 1 to 31).	1
%F	ISO 8601 date format (equivalent to %Y-%m-%d).	2022-04-01
%g	Like %G, but without century, that is, with a 2-digit year.	22
%G	ISO 8601 week-based year with century as a decimal number. The 4-digit year corresponds to the ISO week number (see %V). This has the same format and value as %Y, except that if the ISO week number belongs to the previous or next year, that year is used instead.	2022
%H	Hour as a decimal number using a 24-hour clock (range 00 to 23). See also %k.	17
%I	Hour as a decimal number using a 12-hour clock (range 01 to 12). See also %l.	05
%j	Day of the year as a decimal number (range 001 to 366).	091
%k	Hour as a decimal number using a 24-hour clock (range 0 to 23). See also %H.	17
%l	Hour as a decimal number using a 12-hour clock (range 1 to 12). See also %I.	5
%m	Month as a decimal number (range 01 to 12).	04
%n	Month as a decimal number (range 1 to 12).	4
%M	Minute as a decimal number (range 00 to 59).	15
%p	Either "AM" or "PM" according to the given time value. Noon is treated as "PM" and midnight as "AM".	PM
%P	Like %p but in lowercase ("am" or "pm").	pm
%s	Number of seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC).	1648858500
%S	Second as a decimal number (range 00 to 59).	00
%u	Day of the week as a decimal (range 1 to 7), Monday being 1. See also %w.	5
%V	ISO 8601 week number of the current year as a decimal number (range 01 to 53), where week 1 is the first week that has at least 4 days in the new year (that is, the first Thursday).	13
%w	Day of the week as a decimal (range 0 to 6), Sunday being 0. See also %u.	5
%x	Preferred date representation for the current locale without the time.	4/1/2022
%X	Preferred time representation for the current locale without the date.	5:15:00 PM
%y	Year as a decimal number without a century (range 00 to 99).	22
%Y	Year as a decimal number including the century.	2022
%z	The +hhmm or -hhmm numeric timezone (that is, the hour and minute offset from UTC).	-0800
%Z	Timezone name.	Pacific Standard Time
%Zs	Timezone short name (abbreviation).	PST

Compatibility notes:

• %c - formatted string is slightly different
• %D - not implemented (use %m/%d/%y or %d/%m/%y)
• %e - space is not added
• %E - not implemented
• %h - not implemented (use %b)
• %k - space is not added
• %n - like %m, but no leading zero (use \n for newline)
• %O - not implemented
• %r - not implemented (use %I:%M:%S %p)
• %R - not implemented (use %H:%M)
• %t - not implemented (use \t)
• %T - not implemented (use %H:%M:%S)
• %U - not implemented
• %W - not implemented
• %+ - not implemented
• %% - not implemented (use %)

Sample usage:

// Returns "15-09-2016 16:20"
strftime('%d-%m-%Y %H:%M');

// You can optionally pass it a Date object
// Returns "01-01-2016 21:30"
strftime('%d-%m-%Y %H:%M', new Date('Jan 1, 2016 9:30 PM'));

strftime's Issues

Correction to %V calculation

I think line 92 should read:

return zeroPad(1 + Math.ceil((n1stThu - target.valueOf()) / 604800000), 2);

rather than:

return zeroPad(1 + Math.ceil((n1stThu - target) / 604800000), 2);

Underscores after sequence prevents formatting.

console.log(strftime("%Y_%m_%d_%H_%M_%S_", Date.now()));

Error converting due to wrong date type with instanceOf

Before checking for instanceof, date needs to be converted to Date object
and need to be checked for valid date just incase date is a null or empty string

function strftime(sFormat, sDate) {
	if (typeof sFormat !== 'string') {
	  return '';
	}
	if (sDate == "") {return sDate;}
	let date = new Date(sDate);
	if (!(date instanceof Date  && !isNaN(date))) {
	  return sDate;
	}

FEATURE REQUEST: support for abbreviated timezone

Love this library! I use it all the time in preference to what I consider the incomprehensible and poorly-documented Javascript Date formatters. But the one thing I can't do is get the abbreviate timezone, which I basically always want. The strftime %Z option supposedly returns "the timezone name or abbreviation," which are two very different strings -- e.g. "Eastern Daylight Time" vs "EDT". In practice, it always seems to be the longer version, but either way, since I can't rely on the output, the %Z is worthless to me (and I would imagine the majority of web developers).

The same issue of course occurs in the Unix strftime -- the problem doesn't originate with this library.

So I end up writing my own ugly wrappers around strftime to stitch this in everywhere:

export function shortTz(date?: Date | null): string | undefined {
  if (!date) { return undefined }
  const timeString = date.toLocaleTimeString('en', {timeZoneName: 'short'})
  return timeString.match(' ([A-Z+0-9]+)$')![1]!
}

export function formatTimeWithShortTz(format: string, time: Date): string {
  return `${stftime(format, time)} ${shortTz(time)}`
}

Though strftime is intended to be a port of the Unix version, this one simple enhancement to me vastly increases its usefulness. Would it be possible to extend it to cover this case, with the understanding that abbreviations aren't standardized and may be browser-dependent? Since %Z is non-deterministic anyway, changing it return the abbreviated time zone (which seems more useful and common than the spelled-out one) would not break backwards compatibility. Ideally we could add a second %something for the spelled-out case and cover both.

Question: use of strftime in project

@thdoan
Hello !

I came across your library while working on replacement for a deprecated Firefox function toLocaleFormat()

Your library is excellent and tiny!
Any problem using for a Thunderbird add-on? I will of course give attribution in the contributor section of the manifest. I think the license mixing with the Mozilla license should be okay.

Cheers and thanks in advance.
@cleidigh