TypeScript Dates

A moment with a type

Date is the built-in type for a point in time. You construct it, read year/month/day, and print a stamp. C++ chrono measures durations and clocks; this chapter is the calendar object JavaScript gives you. Types on StudyGrid are checked by tsc; the values are ordinary Date instances at run time.

new Date() uses the clock on the machine. That output changes every run. This tutorial constructs from a fixed ISO string so the printed lines stay the same on every compile.

Construct from an ISO string

Pass a string in ISO 8601 form: YYYY-MM-DDTHH:mm:ss.sssZ. The Z means UTC. Store the result in a Date variable. toISOString() prints that UTC stamp back out.

const stamp = new Date("2026-08-19T15:30:00.000Z");
console.log(stamp.toISOString());
console.log(stamp.getTime());

First line is 2026-08-19T15:30:00.000Z. Second line is the millisecond offset from 1 January 1970 UTC, a fixed integer for this string. Use that integer when you need to subtract two instants.

Read parts in UTC

getUTCFullYear, getUTCMonth, getUTCDate, getUTCHours read the UTC calendar. Month is zero-based: January is 0, August is 7. Add 1 when you print a human month number. Local getters (getHours without UTC) depend on the timezone of the machine, so they are unstable in a tutorial.

const stamp = new Date("2026-08-19T15:30:00.000Z");
console.log(stamp.getUTCFullYear());
console.log(stamp.getUTCMonth() + 1);
console.log(stamp.getUTCDate());
console.log(stamp.getUTCHours());
console.log(stamp.getUTCMinutes());

Output is 2026, 8, 19, 15, 30. Those five numbers match the ISO string. They will not change if you run the file in another timezone.

Subtract two dates

getTime() returns milliseconds. Subtract two of them for a duration. Divide by 1000 for seconds, by 60000 for minutes. This is the same idea as C++ duration_cast, done with ordinary numbers.

const start = new Date("2026-08-19T15:30:00.000Z");
const end = new Date("2026-08-19T15:32:30.000Z");
const ms = end.getTime() - start.getTime();
console.log(ms);
console.log(ms / 1000);
console.log(ms / 60000);

Output is 150000, then 150, then 2.5. Two minutes and thirty seconds live in the two ISO strings, not in the wall clock.

Invalid dates

A bad string still constructs a Date, but getTime() is NaN. Check withNumber.isNaN before you trust parts. Do not print NaN and call it a stamp.

const good = new Date("2026-08-19T15:30:00.000Z");
const bad = new Date("not-a-date");
console.log(Number.isNaN(good.getTime()));
console.log(Number.isNaN(bad.getTime()));

Output is false then true. Only good is a real instant.

What to call

Keep stamps boring

Construct from ISO, read UTC parts, subtract getTime(). Skip locale formatting and timezones until you need them. Next: static, which is about data shared by every object of a class, not about clocks.