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

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

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

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()              │
└─────────────────────────────────────────────────────────────────┘