JavaScript Date Handling Guide

Working with dates in JavaScript requires understanding the Date object and its quirks. Here's a comprehensive guide.

Creating Dates#

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

// From timestamp (milliseconds since Jan 1, 1970)
const fromTimestamp = new Date(1704067200000);

// From string (ISO 8601 recommended)
const fromString = new Date('2024-01-01T12:00:00Z');
const fromDateString = new Date('2024-01-01');

// From components (months are 0-indexed!)
const fromComponents = new Date(2024, 0, 15, 10, 30, 0);
// January 15, 2024, 10:30:00

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

// Invalid date
const invalid = new Date('not a date');
console.log(isNaN(invalid.getTime())); // true

Getting Date Components#

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

// Local time components
date.getFullYear();    // 2024
date.getMonth();       // 5 (June - 0-indexed)
date.getDate();        // 15
date.getDay();         // 6 (Saturday - 0=Sunday)
date.getHours();       // Varies by timezone
date.getMinutes();     // 30
date.getSeconds();     // 45
date.getMilliseconds(); // 123

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

// Timestamp
date.getTime();        // Milliseconds since epoch
Date.now();            // Current timestamp

// Timezone offset (minutes)
date.getTimezoneOffset(); // e.g., -300 for EST

Setting Date Components#

const date = new Date();

// Set individual components
date.setFullYear(2025);
date.setMonth(11);        // December (0-indexed)
date.setDate(25);
date.setHours(12);
date.setMinutes(0);
date.setSeconds(0);
date.setMilliseconds(0);

// Set from timestamp
date.setTime(1704067200000);

// Chaining (returns timestamp, not Date)
const timestamp = new Date()
  .setFullYear(2025);
// timestamp is a number, not Date!

// Method returns new timestamp
const newTimestamp = date.setMonth(5);

Formatting Dates#

const date = new Date('2024-06-15T14:30:00');

// Built-in string methods
date.toString();
// "Sat Jun 15 2024 14:30:00 GMT-0400 (Eastern Daylight Time)"

date.toDateString();     // "Sat Jun 15 2024"
date.toTimeString();     // "14:30:00 GMT-0400 (EDT)"
date.toISOString();      // "2024-06-15T18:30:00.000Z"
date.toUTCString();      // "Sat, 15 Jun 2024 18:30:00 GMT"
date.toLocaleDateString(); // "6/15/2024" (locale-dependent)
date.toLocaleTimeString(); // "2:30:00 PM" (locale-dependent)
date.toLocaleString();   // "6/15/2024, 2:30:00 PM"

// Intl.DateTimeFormat for more control
const formatter = new Intl.DateTimeFormat('en-US', {
  weekday: 'long',
  year: 'numeric',
  month: 'long',
  day: 'numeric'
});

formatter.format(date);  // "Saturday, June 15, 2024"

// Various formats
new Intl.DateTimeFormat('en-US', {
  dateStyle: 'full'
}).format(date);
// "Saturday, June 15, 2024"

new Intl.DateTimeFormat('en-US', {
  dateStyle: 'long',
  timeStyle: 'short'
}).format(date);
// "June 15, 2024 at 2:30 PM"

Custom Formatting#

function formatDate(date, format) {
  const pad = (n) => String(n).padStart(2, '0');

  const replacements = {
    'YYYY': date.getFullYear(),
    'MM': pad(date.getMonth() + 1),
    'DD': pad(date.getDate()),
    'HH': pad(date.getHours()),
    'mm': pad(date.getMinutes()),
    'ss': pad(date.getSeconds()),
    'M': date.getMonth() + 1,
    'D': date.getDate(),
    'H': date.getHours(),
  };

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

formatDate(new Date(), 'YYYY-MM-DD');        // "2024-06-15"
formatDate(new Date(), 'MM/DD/YYYY');        // "06/15/2024"
formatDate(new Date(), 'YYYY-MM-DD HH:mm');  // "2024-06-15 14:30"

// Relative time formatting
const rtf = new Intl.RelativeTimeFormat('en', { numeric: 'auto' });

rtf.format(-1, 'day');     // "yesterday"
rtf.format(1, 'day');      // "tomorrow"
rtf.format(-2, 'hour');    // "2 hours ago"
rtf.format(3, 'month');    // "in 3 months"

Date Arithmetic#

const date = new Date('2024-06-15');

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

addDays(date, 7);   // June 22, 2024
addDays(date, -30); // May 16, 2024

// Add months (handles edge cases)
function addMonths(date, months) {
  const result = new Date(date);
  const day = result.getDate();
  result.setMonth(result.getMonth() + months);

  // Handle month overflow (e.g., Jan 31 + 1 month)
  if (result.getDate() !== day) {
    result.setDate(0); // Last day of previous month
  }

  return result;
}

addMonths(new Date('2024-01-31'), 1); // Feb 29, 2024 (leap year)

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

// Difference between dates
function daysBetween(date1, date2) {
  const MS_PER_DAY = 1000 * 60 * 60 * 24;
  const utc1 = Date.UTC(date1.getFullYear(), date1.getMonth(), date1.getDate());
  const utc2 = Date.UTC(date2.getFullYear(), date2.getMonth(), date2.getDate());
  return Math.floor((utc2 - utc1) / MS_PER_DAY);
}

Comparing Dates#

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

// Compare timestamps
date1.getTime() < date2.getTime();  // true
date1 < date2;  // true (implicit conversion)

// Check equality
date1.getTime() === date2.getTime(); // false
// Don't use: date1 === date2 (different objects)

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

// Is before/after
function isBefore(date1, date2) {
  return date1.getTime() < date2.getTime();
}

function isAfter(date1, date2) {
  return date1.getTime() > date2.getTime();
}

// Is between
function isBetween(date, start, end) {
  const time = date.getTime();
  return time >= start.getTime() && time <= end.getTime();
}

Start/End of Period#

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

Parsing Dates#

// ISO 8601 (recommended)
new Date('2024-06-15T14:30:00Z');      // UTC
new Date('2024-06-15T14:30:00-04:00'); // With offset
new Date('2024-06-15T14:30:00');       // Local time

// Date.parse returns timestamp
Date.parse('2024-06-15');  // Timestamp

// Custom parsing
function parseDate(str, format) {
  const formats = {
    'YYYY-MM-DD': /^(\d{4})-(\d{2})-(\d{2})$/,
    'MM/DD/YYYY': /^(\d{2})\/(\d{2})\/(\d{4})$/,
    'DD.MM.YYYY': /^(\d{2})\.(\d{2})\.(\d{4})$/,
  };

  const regex = formats[format];
  if (!regex) throw new Error('Unknown format');

  const match = str.match(regex);
  if (!match) throw new Error('Invalid date string');

  if (format === 'YYYY-MM-DD') {
    return new Date(+match[1], +match[2] - 1, +match[3]);
  }
  if (format === 'MM/DD/YYYY') {
    return new Date(+match[3], +match[1] - 1, +match[2]);
  }
  if (format === 'DD.MM.YYYY') {
    return new Date(+match[3], +match[2] - 1, +match[1]);
  }
}

parseDate('15.06.2024', 'DD.MM.YYYY');

Timezone Handling#

// Get timezone name
Intl.DateTimeFormat().resolvedOptions().timeZone;
// e.g., "America/New_York"

// Format in specific timezone
function formatInTimezone(date, timezone, options = {}) {
  return new Intl.DateTimeFormat('en-US', {
    ...options,
    timeZone: timezone
  }).format(date);
}

formatInTimezone(new Date(), 'America/New_York', {
  dateStyle: 'full',
  timeStyle: 'long'
});

formatInTimezone(new Date(), 'Europe/London', {
  hour: '2-digit',
  minute: '2-digit'
});

// Convert between timezones (display only)
const date = new Date();
const options = {
  timeZone: 'Asia/Tokyo',
  year: 'numeric',
  month: '2-digit',
  day: '2-digit',
  hour: '2-digit',
  minute: '2-digit'
};
new Intl.DateTimeFormat('ja-JP', options).format(date);

Best Practices#

Creation:
✓ Use ISO 8601 strings
✓ Use Date.UTC for UTC dates
✓ Validate parsed dates
✓ Remember months are 0-indexed

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

Manipulation:
✓ Create new Date objects
✓ Handle month overflow
✓ Use UTC for calculations
✓ Consider timezone differences

Avoid:
✗ Parsing ambiguous formats
✗ Mutating date objects
✗ Ignoring timezones
✗ Using deprecated methods

JavaScript's Date object has quirks (0-indexed months, mutable methods) but is powerful when used correctly. Use ISO 8601 strings for parsing, Intl.DateTimeFormat for locale-aware formatting, and always consider timezones when storing and displaying dates. For complex date manipulation, consider libraries like date-fns or Luxon, but the native Date API handles most common cases effectively.