examples

/**
 * 15.1 Date Fundamentals - Examples
 *
 * The Date object represents a single moment in time.
 * Internally stored as milliseconds since Unix Epoch (Jan 1, 1970).
 */

// ============================================
// 1. CREATING DATES
// ============================================

console.log('=== Creating Dates ===');

// Current date and time
const now = new Date();
console.log('Current date:', now);

// From milliseconds since epoch
const epoch = new Date(0);
console.log('Unix Epoch:', epoch); // 1970-01-01T00:00:00.000Z

const oneDay = 1000 * 60 * 60 * 24; // ms in a day
const dayAfterEpoch = new Date(oneDay);
console.log('Day after epoch:', dayAfterEpoch);

// From date string
console.log('\n--- From Strings ---');
const fromISO = new Date('2024-12-25');
console.log('From ISO:', fromISO);

const fromISOFull = new Date('2024-12-25T10:30:00Z');
console.log('From ISO with time:', fromISOFull);

const fromReadable = new Date('December 25, 2024 10:30:00');
console.log('From readable:', fromReadable);

// From individual components
// NOTE: Month is 0-indexed! (0 = January, 11 = December)
console.log('\n--- From Components ---');
const christmas = new Date(2024, 11, 25); // December 25, 2024
console.log('Christmas 2024:', christmas);

const withTime = new Date(2024, 11, 25, 10, 30, 45, 123);
console.log('With time:', withTime);

// Date.now() - just the timestamp, no object
const timestamp = Date.now();
console.log('\nDate.now():', timestamp);

// ============================================
// 2. MONTH INDEX GOTCHA
// ============================================

console.log('\n=== Month Index (0-based!) ===');

const january = new Date(2024, 0, 1); // Month 0 = January
const december = new Date(2024, 11, 1); // Month 11 = December

console.log('Month 0 (January):', january.toDateString());
console.log('Month 11 (December):', december.toDateString());

// Month names helper
const monthNames = [
  'January',
  'February',
  'March',
  'April',
  'May',
  'June',
  'July',
  'August',
  'September',
  'October',
  'November',
  'December',
];
console.log('\nMonth index 5 =', monthNames[5]); // June

// ============================================
// 3. GETTING DATE COMPONENTS
// ============================================

console.log('\n=== Getting Date Components ===');

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

console.log('\n--- Getters ---');
console.log('getFullYear():', date.getFullYear()); // 2024
console.log('getMonth():', date.getMonth()); // 11 (December)
console.log('getDate():', date.getDate()); // 25 (day of month)
console.log('getDay():', date.getDay()); // Day of week (0=Sun, 6=Sat)
console.log('getHours():', date.getHours()); // 10
console.log('getMinutes():', date.getMinutes()); // 30
console.log('getSeconds():', date.getSeconds()); // 45
console.log('getMilliseconds():', date.getMilliseconds()); // 123
console.log('getTime():', date.getTime()); // ms since epoch

// Day of week
const dayNames = [
  'Sunday',
  'Monday',
  'Tuesday',
  'Wednesday',
  'Thursday',
  'Friday',
  'Saturday',
];
console.log('\nDay of week:', dayNames[date.getDay()]);

// ============================================
// 4. UTC METHODS
// ============================================

console.log('\n=== UTC Methods ===');

const utcDate = new Date('2024-12-25T10:30:00Z'); // Z = UTC
console.log('Date (UTC input):', utcDate);

console.log('\nLocal vs UTC:');
console.log('getHours():', utcDate.getHours(), '(local)');
console.log('getUTCHours():', utcDate.getUTCHours(), '(UTC)');

console.log('getDay():', utcDate.getDay(), '(local)');
console.log('getUTCDay():', utcDate.getUTCDay(), '(UTC)');

// Timezone offset
const offset = utcDate.getTimezoneOffset();
console.log('\nTimezone offset (minutes):', offset);
console.log('Timezone offset (hours):', offset / 60);

// ============================================
// 5. SETTING DATE COMPONENTS
// ============================================

console.log('\n=== Setting Date Components ===');

const modifiable = new Date('2024-06-15T12:00:00');
console.log('Original:', modifiable.toISOString());

modifiable.setFullYear(2025);
console.log('After setFullYear(2025):', modifiable.toISOString());

modifiable.setMonth(0); // January
console.log('After setMonth(0):', modifiable.toISOString());

modifiable.setDate(1);
console.log('After setDate(1):', modifiable.toISOString());

modifiable.setHours(0, 0, 0, 0); // Midnight
console.log('After setHours(0,0,0,0):', modifiable.toISOString());

// Setters return the new timestamp
const newTimestamp = modifiable.setFullYear(2026);
console.log('\nReturn value of setter:', newTimestamp);

// ============================================
// 6. AUTOMATIC DATE ROLLOVER
// ============================================

console.log('\n=== Automatic Date Rollover ===');

// Invalid day rolls over to next month
const jan32 = new Date(2024, 0, 32); // January 32
console.log('January 32, 2024:', jan32.toDateString()); // February 1

const feb30 = new Date(2024, 1, 30); // February 30 (2024 is leap year)
console.log('February 30, 2024:', feb30.toDateString()); // March 1

// Negative values work too
const feb0 = new Date(2024, 1, 0); // Day 0 of February
console.log('February 0, 2024:', feb0.toDateString()); // January 31

// Useful for date arithmetic
const date2 = new Date(2024, 0, 15);
console.log('\nStarting date:', date2.toDateString());

date2.setDate(date2.getDate() + 20);
console.log('After adding 20 days:', date2.toDateString());

date2.setMonth(date2.getMonth() - 1);
console.log('After subtracting 1 month:', date2.toDateString());

// ============================================
// 7. DATE PARSING
// ============================================

console.log('\n=== Date Parsing ===');

// Date.parse() returns milliseconds
console.log("Date.parse('2024-12-25'):", Date.parse('2024-12-25'));
console.log(
  "Date.parse('December 25, 2024'):",
  Date.parse('December 25, 2024')
);
console.log("Date.parse('12/25/2024'):", Date.parse('12/25/2024'));
console.log("Date.parse('invalid'):", Date.parse('invalid')); // NaN

// ISO 8601 - recommended format
console.log('\n--- ISO 8601 Format ---');
const isoDate = '2024-12-25T10:30:00.000Z';
console.log('ISO string:', isoDate);
console.log('Parsed:', new Date(isoDate));

// ============================================
// 8. DATE COMPARISON
// ============================================

console.log('\n=== Date Comparison ===');

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

console.log('date1:', date1.toDateString());
console.log('date3:', date3.toDateString());

// Comparison using operators (auto-converts to number)
console.log('\ndate1 < date3:', date1 < date3); // true
console.log('date1 > date3:', date1 > date3); // false

// Equality - must use getTime()
console.log('\ndate1 === date1Copy:', date1 === date1Copy); // false (different objects)
console.log(
  'date1.getTime() === date1Copy.getTime():',
  date1.getTime() === date1Copy.getTime()
); // true

// Sorting dates
const dates = [
  new Date('2024-06-15'),
  new Date('2024-01-01'),
  new Date('2024-12-31'),
  new Date('2024-03-20'),
];

console.log(
  '\nUnsorted:',
  dates.map((d) => d.toDateString())
);

const sorted = [...dates].sort((a, b) => a - b);
console.log(
  'Sorted (ascending):',
  sorted.map((d) => d.toDateString())
);

// ============================================
// 9. STATIC METHODS
// ============================================

console.log('\n=== Static Methods ===');

// Date.now() - current timestamp
console.log('Date.now():', Date.now());

// Date.parse() - parse string to ms
console.log("Date.parse('2024-12-25'):", Date.parse('2024-12-25'));

// Date.UTC() - create UTC timestamp from components
const utcTimestamp = Date.UTC(2024, 11, 25, 10, 30, 0);
console.log('Date.UTC(2024, 11, 25, 10, 30, 0):', utcTimestamp);
console.log('As Date:', new Date(utcTimestamp));

// ============================================
// 10. DATE STRING METHODS
// ============================================

console.log('\n=== Date String Methods ===');

const displayDate = new Date('2024-12-25T10:30:45.123');
console.log('Original date:', displayDate);

console.log('\n--- String Methods ---');
console.log('toString():', displayDate.toString());
console.log('toDateString():', displayDate.toDateString());
console.log('toTimeString():', displayDate.toTimeString());
console.log('toISOString():', displayDate.toISOString());
console.log('toUTCString():', displayDate.toUTCString());
console.log('toJSON():', displayDate.toJSON());

console.log('\n--- Locale Methods ---');
console.log('toLocaleString():', displayDate.toLocaleString());
console.log('toLocaleDateString():', displayDate.toLocaleDateString());
console.log('toLocaleTimeString():', displayDate.toLocaleTimeString());

// With options
console.log('\n--- Locale with Options ---');
console.log(
  'US format:',
  displayDate.toLocaleDateString('en-US', {
    weekday: 'long',
    year: 'numeric',
    month: 'long',
    day: 'numeric',
  })
);

console.log(
  'German format:',
  displayDate.toLocaleDateString('de-DE', {
    weekday: 'long',
    year: 'numeric',
    month: 'long',
    day: 'numeric',
  })
);

// ============================================
// 11. COMMON PATTERNS
// ============================================

console.log('\n=== Common Patterns ===');

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

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

const today = new Date();
console.log('--- Start/End of Day ---');
console.log('Now:', today.toISOString());
console.log('Start of day:', startOfDay(today).toISOString());
console.log('End of day:', endOfDay(today).toISOString());

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

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

console.log('\n--- Start/End of Month ---');
console.log('Start of month:', startOfMonth(today).toDateString());
console.log('End of month:', endOfMonth(today).toDateString());

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

console.log('\n--- Valid Date Check ---');
console.log('isValidDate(new Date()):', isValidDate(new Date())); // true
console.log(
  "isValidDate(new Date('invalid')):",
  isValidDate(new Date('invalid'))
); // false
console.log("isValidDate('2024-01-01'):", isValidDate('2024-01-01')); // false (not a Date)

// Clone a date
function cloneDate(date) {
  return new Date(date.getTime());
}

const original = new Date();
const clone = cloneDate(original);
clone.setFullYear(2030);

console.log('\n--- Clone Date ---');
console.log('Original:', original.getFullYear());
console.log('Clone (modified):', clone.getFullYear());

// ============================================
// 12. TIMEZONE HANDLING
// ============================================

console.log('\n=== Timezone Handling ===');

// Same timestamp, different interpretations
const withZ = new Date('2024-12-25T10:30:00Z'); // UTC
const withoutZ = new Date('2024-12-25T10:30:00'); // Local time

console.log('With Z (UTC):', withZ.toString());
console.log('Without Z (Local):', withoutZ.toString());
console.log('Are they equal?', withZ.getTime() === withoutZ.getTime()); // Depends on timezone

// Date-only strings are parsed as UTC
const dateOnly = new Date('2024-12-25');
console.log('\nDate-only string parsed as:', dateOnly.toISOString());

// Always store/transmit in ISO format
const forStorage = new Date().toISOString();
console.log('\nFor storage/API:', forStorage);

console.log('\n=== Examples Complete ===');