15.1 Date Fundamentals

Overview

JavaScript's Date object represents a single moment in time. Dates are stored internally as the number of milliseconds since January 1, 1970, 00:00:00 UTC (the Unix Epoch). Understanding how dates work is essential for handling time-based data in applications.

The Date Object

┌─────────────────────────────────────────────────────────────────┐
│                      JavaScript Date                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   Internally stored as: milliseconds since Unix Epoch           │
│                                                                  │
│   Unix Epoch: January 1, 1970, 00:00:00 UTC                     │
│                                                                  │
│   ┌─────────────────────────────────────────────────────────┐   │
│   │  Negative ms  │  Epoch (0)  │     Positive ms           │   │
│   │  (before 1970) │  1970-01-01 │     (after 1970)          │   │
│   └───────────────┴─────────────┴───────────────────────────┘   │
│                                                                  │
│   Range: ±100,000,000 days from epoch                           │
│          (~±273,790 years)                                      │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Creating Dates

Different Constructors

// 1. Current date and time
const now = new Date();

// 2. From milliseconds since epoch
const fromMs = new Date(0); // 1970-01-01T00:00:00.000Z
const later = new Date(1000 * 60 * 60 * 24); // 1 day after epoch

// 3. From date string
const fromString = new Date('2024-12-25');
const fromISO = new Date('2024-12-25T10:30:00Z');
const fromReadable = new Date('December 25, 2024 10:30:00');

// 4. From individual components (year, month, day, hours, min, sec, ms)
// Note: Month is 0-indexed (0 = January, 11 = December)
const fromComponents = new Date(2024, 11, 25); // Dec 25, 2024
const withTime = new Date(2024, 11, 25, 10, 30, 0, 0); // 10:30:00.000

// 5. Date.now() - milliseconds since epoch (no object created)
const timestamp = Date.now();

Month Index Gotcha

┌─────────────────────────────────────────────────────────────────┐
│                    Month Index (0-based!)                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   0 = January      4 = May          8 = September               │
│   1 = February     5 = June         9 = October                 │
│   2 = March        6 = July        10 = November                │
│   3 = April        7 = August      11 = December                │
│                                                                  │
│   new Date(2024, 0, 1)  → January 1, 2024                       │
│   new Date(2024, 11, 25) → December 25, 2024                    │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Getting Date Components

Method	Returns	Range
`getFullYear()`	4-digit year	e.g., 2024
`getMonth()`	Month index	0-11
`getDate()`	Day of month	1-31
`getDay()`	Day of week	0-6 (Sun-Sat)
`getHours()`	Hours	0-23
`getMinutes()`	Minutes	0-59
`getSeconds()`	Seconds	0-59
`getMilliseconds()`	Milliseconds	0-999
`getTime()`	Ms since epoch	Number

const date = new Date('2024-12-25T10:30:45.123');

date.getFullYear(); // 2024
date.getMonth(); // 11 (December)
date.getDate(); // 25
date.getDay(); // 3 (Wednesday)
date.getHours(); // 10
date.getMinutes(); // 30
date.getSeconds(); // 45
date.getMilliseconds(); // 123
date.getTime(); // 1735123845123 (ms since epoch)

UTC Methods

All getters have UTC equivalents that return values in UTC instead of local time:

const date = new Date('2024-12-25T10:30:00Z');

date.getHours(); // Local hours (depends on timezone)
date.getUTCHours(); // 10 (always UTC)

date.getTimezoneOffset(); // Difference in minutes between local and UTC
// e.g., -300 for EST (UTC-5)

Setting Date Components

Method	Sets
`setFullYear(year, [month], [date])`	Year (and optionally month/date)
`setMonth(month, [date])`	Month (and optionally date)
`setDate(date)`	Day of month
`setHours(hours, [min], [sec], [ms])`	Hours (and optionally others)
`setMinutes(min, [sec], [ms])`	Minutes
`setSeconds(sec, [ms])`	Seconds
`setMilliseconds(ms)`	Milliseconds
`setTime(ms)`	Set by milliseconds since epoch

const date = new Date();

date.setFullYear(2025);
date.setMonth(0); // January
date.setDate(1);
date.setHours(0, 0, 0, 0); // Midnight

// Setters return the new timestamp
const newTime = date.setFullYear(2026); // Returns ms since epoch

Automatic Date Rollover

// JavaScript automatically adjusts invalid dates
const date = new Date(2024, 0, 32); // January 32
console.log(date); // February 1, 2024

const date2 = new Date(2024, 1, 30); // February 30
console.log(date2); // March 1, 2024 (or Feb 29 in leap year)

// This is useful for date arithmetic
date.setDate(date.getDate() + 7); // Add 7 days
date.setMonth(date.getMonth() - 1); // Subtract 1 month

Date Parsing

Date.parse()

// Returns milliseconds since epoch, or NaN for invalid
Date.parse('2024-12-25'); // Works
Date.parse('December 25, 2024'); // Works
Date.parse('12/25/2024'); // Works (US format)
Date.parse('2024-12-25T10:30:00Z'); // ISO 8601
Date.parse('invalid'); // NaN

ISO 8601 Format (Recommended)

┌─────────────────────────────────────────────────────────────────┐
│                    ISO 8601 Date Format                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   YYYY-MM-DDTHH:mm:ss.sssZ                                      │
│                                                                  │
│   2024-12-25T10:30:00.000Z                                      │
│   │    │  │ │ │  │  │   │                                       │
│   │    │  │ │ │  │  │   └── Z = UTC (or +HH:mm for timezone)    │
│   │    │  │ │ │  │  └────── milliseconds (optional)             │
│   │    │  │ │ │  └───────── seconds                             │
│   │    │  │ │ └──────────── minutes                             │
│   │    │  │ └────────────── hours (24-hour)                     │
│   │    │  └──────────────── day                                 │
│   │    └─────────────────── month                               │
│   └──────────────────────── year                                │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

// ISO format is unambiguous and recommended
const iso = '2024-12-25T10:30:00.000Z';
const date = new Date(iso);

// Convert to ISO string
date.toISOString(); // "2024-12-25T10:30:00.000Z"

Date Comparison

const date1 = new Date('2024-01-01');
const date2 = new Date('2024-12-31');

// Compare using getTime() or valueOf()
date1.getTime() < date2.getTime(); // true
date1 < date2; // true (auto-converts to number)
date1.valueOf() === date2.valueOf(); // false

// Equality check (must use getTime())
date1 === date2; // false (different objects)
date1.getTime() === date2.getTime(); // true (if same timestamp)

// Sort dates
const dates = [date2, date1];
dates.sort((a, b) => a - b); // Ascending order
dates.sort((a, b) => b - a); // Descending order

Static Methods

// Date.now() - current timestamp in ms
const now = Date.now();

// Date.parse() - parse string to ms
const ms = Date.parse('2024-12-25');

// Date.UTC() - create timestamp from UTC components
const utcMs = Date.UTC(2024, 11, 25, 10, 30, 0);
const utcDate = new Date(utcMs);

Date String Methods

Method	Output Example
`toString()`	"Wed Dec 25 2024 10:30:00 GMT-0500"
`toDateString()`	"Wed Dec 25 2024"
`toTimeString()`	"10:30:00 GMT-0500"
`toISOString()`	"2024-12-25T15:30:00.000Z"
`toUTCString()`	"Wed, 25 Dec 2024 15:30:00 GMT"
`toLocaleDateString()`	"12/25/2024" (locale-dependent)
`toLocaleTimeString()`	"10:30:00 AM" (locale-dependent)
`toLocaleString()`	"12/25/2024, 10:30:00 AM"
`toJSON()`	"2024-12-25T15:30:00.000Z"

Common Patterns

Get Start/End of Day

function startOfDay(date) {
  const result = new Date(date);
  result.setHours(0, 0, 0, 0);
  return result;
}

function endOfDay(date) {
  const result = new Date(date);
  result.setHours(23, 59, 59, 999);
  return result;
}

Get Start/End of Month

function startOfMonth(date) {
  return new Date(date.getFullYear(), date.getMonth(), 1);
}

function endOfMonth(date) {
  return new Date(date.getFullYear(), date.getMonth() + 1, 0);
}

Check if Valid Date

function isValidDate(date) {
  return date instanceof Date && !isNaN(date.getTime());
}

isValidDate(new Date('2024-12-25')); // true
isValidDate(new Date('invalid')); // false

Timezone Considerations

┌─────────────────────────────────────────────────────────────────┐
│                    Timezone Handling                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   JavaScript Date stores time in UTC internally                 │
│   Display methods convert to local timezone                     │
│                                                                  │
│   "2024-12-25T10:30:00Z"      → Parsed as UTC                   │
│   "2024-12-25T10:30:00"       → Parsed as LOCAL time            │
│   "2024-12-25"                → Parsed as UTC (date-only)       │
│                                                                  │
│   Best Practices:                                                │
│   • Store dates in UTC                                          │
│   • Use ISO 8601 format for exchange                            │
│   • Convert to local time only for display                      │
│   • Consider using Temporal API (upcoming) for complex needs    │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Key Takeaways

┌─────────────────────────────────────────────────────────────────┐
│                    Date Fundamentals                             │
├─────────────────────────────────────────────────────────────────┤
│  1. Dates store milliseconds since Jan 1, 1970 UTC              │
│  2. Months are 0-indexed (January = 0)                          │
│  3. Days of week: 0 = Sunday, 6 = Saturday                      │
│  4. Use getTime() for comparison and equality                   │
│  5. Setters auto-correct invalid dates (rollover)               │
│  6. Use ISO 8601 format for reliable parsing                    │
│  7. getTimezoneOffset() returns minutes (not hours)             │
│  8. Date.now() is faster than new Date().getTime()              │
└─────────────────────────────────────────────────────────────────┘

9.1-Date-Fundamentals