JavaScript Date Manipulation

Working with dates in JavaScript requires understanding quirks and patterns. Here's a comprehensive guide.

Creating Dates#

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

// From string (ISO 8601 preferred)
const fromISO = new Date('2024-03-15T14:30:00Z');
const fromDate = new Date('2024-03-15');

// From components (months are 0-indexed!)
const fromParts = new Date(2024, 2, 15, 14, 30, 0); // March 15, 2024

// From timestamp (milliseconds since Unix epoch)
const fromTimestamp = new Date(1710510600000);

// UTC date
const utc = new Date(Date.UTC(2024, 2, 15, 14, 30, 0));

// Parse with explicit timezone
const withTimezone = new Date('2024-03-15T14:30:00-05:00');

Getters and Setters#

const date = new Date('2024-03-15T14:30:45.123Z');

// Getters (local time)
date.getFullYear();      // 2024
date.getMonth();         // 2 (March, 0-indexed)
date.getDate();          // 15
date.getDay();           // 5 (Friday, 0 = Sunday)
date.getHours();         // Varies by timezone
date.getMinutes();       // 30
date.getSeconds();       // 45
date.getMilliseconds();  // 123

// Getters (UTC)
date.getUTCFullYear();   // 2024
date.getUTCMonth();      // 2
date.getUTCDate();       // 15
date.getUTCHours();      // 14
date.getUTCMinutes();    // 30

// Timestamp
date.getTime();          // 1710510645123
Date.now();              // Current timestamp

// Setters (mutate the date!)
const mutable = new Date();
mutable.setFullYear(2025);
mutable.setMonth(5);     // June
mutable.setDate(20);
mutable.setHours(12, 0, 0, 0); // 12:00:00.000

Date Arithmetic#

// Add days
function addDays(date, days) {
  const result = new Date(date);
  result.setDate(result.getDate() + days);
  return result;
}

// Add months (handles month overflow)
function addMonths(date, months) {
  const result = new Date(date);
  result.setMonth(result.getMonth() + months);
  return result;
}

// Add years
function addYears(date, years) {
  const result = new Date(date);
  result.setFullYear(result.getFullYear() + years);
  return result;
}

// Difference in days
function diffInDays(date1, date2) {
  const msPerDay = 24 * 60 * 60 * 1000;
  return Math.round((date2 - date1) / msPerDay);
}

// Difference in months
function diffInMonths(date1, date2) {
  return (
    (date2.getFullYear() - date1.getFullYear()) * 12 +
    date2.getMonth() - date1.getMonth()
  );
}

// Usage
const today = new Date();
const nextWeek = addDays(today, 7);
const nextMonth = addMonths(today, 1);
const nextYear = addYears(today, 1);

Formatting Dates#

// Built-in methods
const date = new Date('2024-03-15T14:30:00');

date.toISOString();        // '2024-03-15T14:30:00.000Z'
date.toDateString();       // 'Fri Mar 15 2024'
date.toTimeString();       // '14:30:00 GMT-0400'
date.toLocaleDateString(); // '3/15/2024' (US locale)
date.toLocaleTimeString(); // '2:30:00 PM'
date.toLocaleString();     // '3/15/2024, 2:30:00 PM'

// Intl.DateTimeFormat
const formatter = new Intl.DateTimeFormat('en-US', {
  year: 'numeric',
  month: 'long',
  day: 'numeric',
  weekday: 'long',
});
formatter.format(date); // 'Friday, March 15, 2024'

// Custom format function
function formatDate(date, format) {
  const map = {
    'YYYY': date.getFullYear(),
    'MM': String(date.getMonth() + 1).padStart(2, '0'),
    'DD': String(date.getDate()).padStart(2, '0'),
    'HH': String(date.getHours()).padStart(2, '0'),
    'mm': String(date.getMinutes()).padStart(2, '0'),
    'ss': String(date.getSeconds()).padStart(2, '0'),
  };

  return format.replace(/YYYY|MM|DD|HH|mm|ss/g, match => map[match]);
}

formatDate(date, 'YYYY-MM-DD'); // '2024-03-15'
formatDate(date, 'DD/MM/YYYY HH:mm'); // '15/03/2024 14:30'

Comparison#

const date1 = new Date('2024-03-15');
const date2 = new Date('2024-03-20');

// Compare timestamps
date1 < date2;  // true
date1 > date2;  // false
date1.getTime() === date2.getTime(); // false

// Check same day
function isSameDay(d1, d2) {
  return (
    d1.getFullYear() === d2.getFullYear() &&
    d1.getMonth() === d2.getMonth() &&
    d1.getDate() === d2.getDate()
  );
}

// Check if date is between
function isBetween(date, start, end) {
  return date >= start && date <= end;
}

// Check if past/future
function isPast(date) {
  return date < new Date();
}

function isFuture(date) {
  return date > new Date();
}

// Check if today
function isToday(date) {
  return isSameDay(date, new Date());
}

Start/End of Periods#

// 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;
}

// Start of month
function startOfMonth(date) {
  const result = new Date(date);
  result.setDate(1);
  result.setHours(0, 0, 0, 0);
  return result;
}

// End of month
function endOfMonth(date) {
  const result = new Date(date);
  result.setMonth(result.getMonth() + 1);
  result.setDate(0);
  result.setHours(23, 59, 59, 999);
  return result;
}

// Start of week (Sunday)
function startOfWeek(date) {
  const result = new Date(date);
  const day = result.getDay();
  result.setDate(result.getDate() - day);
  result.setHours(0, 0, 0, 0);
  return result;
}

// Start of year
function startOfYear(date) {
  return new Date(date.getFullYear(), 0, 1);
}

Timezone Handling#

// Get timezone offset in minutes
const offset = new Date().getTimezoneOffset(); // e.g., 240 for UTC-4

// Convert to different timezone display
function toTimezone(date, timezone) {
  return new Intl.DateTimeFormat('en-US', {
    timeZone: timezone,
    year: 'numeric',
    month: '2-digit',
    day: '2-digit',
    hour: '2-digit',
    minute: '2-digit',
    second: '2-digit',
    hour12: false,
  }).format(date);
}

toTimezone(new Date(), 'America/New_York');
toTimezone(new Date(), 'Europe/London');
toTimezone(new Date(), 'Asia/Tokyo');

// Parse date in specific timezone
function parseInTimezone(dateStr, timezone) {
  // Create formatter for the timezone
  const formatter = new Intl.DateTimeFormat('en-US', {
    timeZone: timezone,
    year: 'numeric',
    month: 'numeric',
    day: 'numeric',
    hour: 'numeric',
    minute: 'numeric',
    second: 'numeric',
    hour12: false,
  });

  // This is a simplified approach - for production use a library
  const date = new Date(dateStr);
  return date;
}

Working with UTC#

// Create UTC date
const utcDate = new Date(Date.UTC(2024, 2, 15, 14, 30, 0));

// Get UTC components
const year = utcDate.getUTCFullYear();
const month = utcDate.getUTCMonth();
const day = utcDate.getUTCDate();
const hours = utcDate.getUTCHours();

// Convert local to UTC
function toUTC(date) {
  return new Date(date.toISOString());
}

// Get current UTC time
function nowUTC() {
  const now = new Date();
  return new Date(
    Date.UTC(
      now.getUTCFullYear(),
      now.getUTCMonth(),
      now.getUTCDate(),
      now.getUTCHours(),
      now.getUTCMinutes(),
      now.getUTCSeconds()
    )
  );
}

Common Utilities#

// Days in month
function getDaysInMonth(year, month) {
  return new Date(year, month + 1, 0).getDate();
}

// Is leap year
function isLeapYear(year) {
  return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
}

// Get week number (ISO)
function getWeekNumber(date) {
  const d = new Date(Date.UTC(date.getFullYear(), date.getMonth(), date.getDate()));
  const dayNum = d.getUTCDay() || 7;
  d.setUTCDate(d.getUTCDate() + 4 - dayNum);
  const yearStart = new Date(Date.UTC(d.getUTCFullYear(), 0, 1));
  return Math.ceil((((d - yearStart) / 86400000) + 1) / 7);
}

// Get quarter
function getQuarter(date) {
  return Math.floor(date.getMonth() / 3) + 1;
}

// Format relative time
function formatRelative(date) {
  const rtf = new Intl.RelativeTimeFormat('en', { numeric: 'auto' });
  const now = new Date();
  const diffMs = date - now;
  const diffSecs = Math.round(diffMs / 1000);
  const diffMins = Math.round(diffSecs / 60);
  const diffHours = Math.round(diffMins / 60);
  const diffDays = Math.round(diffHours / 24);

  if (Math.abs(diffSecs) < 60) return rtf.format(diffSecs, 'second');
  if (Math.abs(diffMins) < 60) return rtf.format(diffMins, 'minute');
  if (Math.abs(diffHours) < 24) return rtf.format(diffHours, 'hour');
  return rtf.format(diffDays, 'day');
}

Validation#

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

// Parse and validate
function parseDate(str) {
  const date = new Date(str);
  if (!isValidDate(date)) {
    throw new Error(`Invalid date: ${str}`);
  }
  return date;
}

// Validate date components
function isValidDateComponents(year, month, day) {
  const date = new Date(year, month, day);
  return (
    date.getFullYear() === year &&
    date.getMonth() === month &&
    date.getDate() === day
  );
}

// Validate range
function isInRange(date, min, max) {
  return date >= min && date <= max;
}

Date Range Generation#

// Generate date range
function* dateRange(start, end) {
  const current = new Date(start);
  while (current <= end) {
    yield new Date(current);
    current.setDate(current.getDate() + 1);
  }
}

// Get all dates in month
function getDatesInMonth(year, month) {
  const start = new Date(year, month, 1);
  const end = new Date(year, month + 1, 0);
  return [...dateRange(start, end)];
}

// Get weekdays between dates
function getWeekdays(start, end) {
  const dates = [];
  const current = new Date(start);

  while (current <= end) {
    const day = current.getDay();
    if (day !== 0 && day !== 6) {
      dates.push(new Date(current));
    }
    current.setDate(current.getDate() + 1);
  }

  return dates;
}

Best Practices#

Creating Dates:
✓ Use ISO 8601 format for strings
✓ Remember months are 0-indexed
✓ Be explicit about timezone
✓ Use Date.UTC for UTC dates

Manipulation:
✓ Always create new Date objects (immutability)
✓ Use setters carefully (they mutate)
✓ Handle month overflow correctly
✓ Test edge cases (DST, leap years)

Formatting:
✓ Use Intl.DateTimeFormat for localization
✓ Store dates in UTC
✓ Display in user's timezone
✓ Use ISO format for APIs

Comparison:
✓ Compare timestamps, not objects
✓ Normalize to same timezone
✓ Consider start/end of day
✓ Handle invalid dates

JavaScript date handling requires attention to timezones, zero-indexed months, and mutability. Use native Date for simple cases, Intl for formatting, and consider libraries like date-fns for complex operations. Always store in UTC and display in local time.