API Reference Date & Time

// Date Getters

const date = new Date('2024-12-31T23:59:59');

// Local time getters
date.getFullYear()      // 2024
date.getMonth()         // 11 (December, 0-indexed!)
date.getDate()          // 31 (day of month)
date.getDay()           // 2 (Tuesday, 0=Sunday)
date.getHours()         // 23
date.getMinutes()       // 59
date.getSeconds()       // 59
date.getMilliseconds()  // 0

// UTC getters (recommended for storage)
date.getUTCFullYear()
date.getUTCMonth()
date.getUTCDate()
date.getUTCHours()
// ... etc

// Timestamp
date.getTime()          // Milliseconds since epoch
date.valueOf()          // Same as getTime()

// Timezone offset
date.getTimezoneOffset() // Minutes from UTC

// Date Setters (mutate the date object!)

const date = new Date('2024-12-31');

// Local time setters
date.setFullYear(2025)
date.setMonth(0)           // January (0-indexed!)
date.setDate(1)            // Day of month
date.setHours(12)
date.setMinutes(30)
date.setSeconds(45)
date.setMilliseconds(500)

// UTC setters (recommended)
date.setUTCFullYear(2025)
date.setUTCMonth(0)
date.setUTCDate(1)
// ... etc

// Set from timestamp
date.setTime(1735689599000)

// Multiple components at once
date.setFullYear(2025, 0, 1)  // Jan 1, 2025
date.setHours(12, 30, 45)     // 12:30:45

// Note: Setters are mutable!
// Consider using libraries for immutable operations

// Date Formatting Methods

const date = new Date('2024-12-31T23:59:59Z');

// ISO format
date.toISOString()          // '2024-12-31T23:59:59.000Z'
date.toJSON()               // Same as toISOString()

// Locale-aware formatting
date.toLocaleDateString()   // '12/31/2024' (varies by locale)
date.toLocaleTimeString()   // '11:59:59 PM' (varies by locale)
date.toLocaleString()       // Date + time

// With locale parameter
date.toLocaleDateString('en-GB')   // '31/12/2024'
date.toLocaleDateString('en-US')   // '12/31/2024'
date.toLocaleDateString('ja-JP')   // '2024/12/31'

// With options
date.toLocaleDateString('en-US', {
  year: 'numeric',
  month: 'long',
  day: 'numeric'
})  // 'December 31, 2024'

// String representations
date.toString()             // Full string with timezone
date.toDateString()         // 'Tue Dec 31 2024'
date.toTimeString()         // '23:59:59 GMT+0000 (UTC)'
date.toUTCString()          // 'Tue, 31 Dec 2024 23:59:59 GMT'

// Static Date Methods

// Current timestamp
Date.now()                  // Current time in ms since epoch

// Parse date string
Date.parse('2024-12-31')    // Returns timestamp
Date.parse('Dec 31, 2024')  // Also works
Date.parse('invalid')       // Returns NaN

// Create from components
Date.UTC(2024, 11, 31)      // Returns UTC timestamp
Date.UTC(2024, 11, 31, 23, 59, 59)

// Common patterns

// Days between dates
const diff = date2 - date1;
const daysDiff = Math.floor(diff / (1000 * 60 * 60 * 24));

// Add days
const tomorrow = new Date(Date.now() + 24 * 60 * 60 * 1000);

// Start of day (midnight)
const startOfDay = new Date(date);
startOfDay.setHours(0, 0, 0, 0);

// End of day
const endOfDay = new Date(date);
endOfDay.setHours(23, 59, 59, 999);