This project is part of the @thi.ng/umbrella monorepo.
Date/timestamp iterators, formatters, rounding.
ALPHA - bleeding edge / work-in-progress
Search or submit any issues for this package
yarn add @thi.ng/date// ES module
<script type="module" src="https://unpkg.com/@thi.ng/date?module" crossorigin></script>
// UMD
<script src="https://unpkg.com/@thi.ng/date/lib/index.umd.js" crossorigin></script>Package sizes (gzipped, pre-treeshake): ESM: 1.75 KB / CJS: 1.91 KB / UMD: 1.90 KB
TODO - Please see tests and doc strings in source for now...
The DateTime class acts as a thin wrapper around UTC epochs/timestamps,
with the constructor supporting coercions and varying granularity/precision
(from years to milliseconds). The main use case of this class is as backend for
the various epoch iterators provided by this package, which in turn are largely
intended for visualization purposes (axis tick label generators in
@thi.ng/viz).
// create w/ current date (or pass epoch, Date or DateTime instances)
const a = dateTime();
// DateTime { y: 2020, M: 8, d: 19, h: 12, m: 17, s: 16, t: 884 }
// provide additional precision (here year only)
const b = dateTime(a, "y");
// DateTime { y: 2020, M: 0, d: 1, h: 0, m: 0, s: 0, t: 0 }
a.toString();
// Sat Sep 19 2020 12:17:16 GMT'
a.toISOString()
// '2020-09-19T12:17:16.884Z'
b.toISOString();
// 2020-01-01T00:00:00.000Z
a.isLeapYear()
// true
a.daysInMonth()
// 30
[...months(b, a)]
// [
// 1577836800000,
// 1580515200000,
// 1583020800000,
// 1585699200000,
// 1588291200000,
// 1590969600000,
// 1593561600000,
// 1596240000000,
// 1598918400000
// ]
[...months(b, a)].map((x) => FMT_yyyyMMdd(x))
// [
// '2020-01-01',
// '2020-02-01',
// '2020-03-01',
// '2020-04-01',
// '2020-05-01',
// '2020-06-01',
// '2020-07-01',
// '2020-08-01',
// '2020-09-01'
// ]Custom date/time formatters can be assembled via
defFormat(),
using the following partial format identifiers. The MMM and E formatters use the currently active locale.
| ID | Description |
|---|---|
yyyy |
Full year (4 digits) |
yy |
Short year (2 digits) |
MMM |
Month name in current locale (e.g. Feb) |
MM |
Zero-padded 2-digit month |
M |
Unpadded month |
dd |
Zero-padded 2-digit day of month |
d |
Unpadded day of month |
E |
Weekday name in current locale (e.g. Mon) |
HH |
Zero-padded 2-digit hour of day (0-23) |
h |
Unpadded hour of day (1-12) |
mm |
Zero-padded 2-digit minute of hour |
m |
Unpadded minute of hour |
ss |
Zero-padded 2-digit second of minute |
s |
Unpadded second of minute |
S |
Unpadded millisecond of second |
A |
12-hour AM/PM marker |
Z |
Timezone offset in signed HH:mm format |
(Format IDs somewhat based on Java's SimpleDateFormat)
The following preset formatters are available:
FMT_yyyyMMdd-"2020-09-13"FMT_Mdyyyy-"9/13/2020"FMT_MMMdyyyy-"Sep 13 2020"FMT_dMyyyy-"13/9/2020"FMT_dMMMyyyy-"13 Sep 2020"FMT_yyyyMMdd_HHmmss-20200913-214207FMT_HHmm-"21:42"FMT_hm-"9:42 PM"FMT_HHmmss-"21:42:07"FMT_hms-"9:42:07 PM"
For timebased media applications, the higher-order defTimecode() can be used
to create a formatter for a given FPS (frames / second, in [1..1000] range),
e.g. HH:mm:ss:ff. The returned function takes a single arg (time in
milliseconds) and returns formatted string.
The timecode considers days too, but only includes them in the result if the day
part is non-zero. The 4 separators between each field can be customized via 2nd
arg (default: all :).
a = defTimecode(30);
a(HOUR + 2*MINUTE + 3*SECOND + 4*1000/30)
// "01:02:03:04"
a(DAY);
// "01:00:00:00:00"
b = defTimecode(30, ["d ", "h ", "' ", '" ']);
b(Day + HOUR + 2*MINUTE + 3*SECOND + 999)
// "01d 01h 02' 03" 29"The MMM (month) and E (weekday) formatters make use of the strings provided
by the current LOCALE (default: EN_SHORT) and can be set/changed via the
setLocale() function:
const fmt = defFormat(["E", " ", "d", " ", "MMM", " ", "yyyy"]);
setLocale(EN_SHORT); // default
// {
// months: [
// 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
// 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
// ],
// days: [ 'Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat' ]
// }
fmt(dateTime());
// Sat 19 Sep 2020
setLocale(EN_LONG);
// {
// months: [
// 'January', 'February', 'March', 'April', 'May', 'June',
// 'July', 'August', 'September', 'October', 'November', 'December'
// ],
// days: [
// 'Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'
// ]
// }
fmt(dateTime());
// Saturday 19 September 2020Karsten Schmidt
If this project contributes to an academic publication, please cite it as:
@misc{thing-date,
title = "@thi.ng/date",
author = "Karsten Schmidt",
note = "https://thi.ng/date",
year = 2020
}© 2020 - 2021 Karsten Schmidt // Apache Software License 2.0