JavaScript Date Handling Guide

Working with dates in JavaScript requires understanding 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(1609459200000);

// From string (ISO 8601)
const fromISO = new Date('2021-01-01T00:00:00.000Z');

// From string (various formats)
const fromString1 = new Date('January 1, 2021');
const fromString2 = new Date('01/01/2021');
const fromString3 = new Date('2021-01-01');

// From components (month is 0-indexed!)
const fromComponents = new Date(2021, 0, 1, 12, 30, 0);
// Year, Month (0-11), Day, Hours, Minutes, Seconds, Milliseconds

// UTC date
const utcDate = new Date(Date.UTC(2021, 0, 1, 12, 0, 0));

Getting Date Components#

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

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

// UTC components
date.getUTCFullYear();  // 2021
date.getUTCMonth();     // 5
date.getUTCDate();      // 15
date.getUTCHours();     // 14

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

// Timezone offset (minutes)
date.getTimezoneOffset(); // e.g., -240 for UTC-4

Setting Date Components#

const date = new Date();

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

// Set UTC components
date.setUTCFullYear(2022);
date.setUTCMonth(11);
date.setUTCDate(25);

// Set timestamp
date.setTime(1640433600000);

// Chaining (returns timestamp)
new Date().setFullYear(2022); // Returns timestamp, not Date

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

Date Formatting#

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

// Built-in methods
date.toString();        // "Tue Jun 15 2021 14:30:00 GMT-0400"
date.toDateString();    // "Tue Jun 15 2021"
date.toTimeString();    // "14:30:00 GMT-0400"
date.toISOString();     // "2021-06-15T18:30:00.000Z"
date.toUTCString();     // "Tue, 15 Jun 2021 18:30:00 GMT"
date.toLocaleDateString(); // "6/15/2021" (varies by locale)
date.toLocaleTimeString(); // "2:30:00 PM" (varies by locale)
date.toLocaleString();  // "6/15/2021, 2:30:00 PM"

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

// More options
const timeFormatter = new Intl.DateTimeFormat('en-US', {
  hour: 'numeric',
  minute: '2-digit',
  second: '2-digit',
  hour12: true,
  timeZoneName: 'short',
});
timeFormatter.format(date); // "2:30:00 PM EDT"

// Relative time
const rtf = new Intl.RelativeTimeFormat('en', { numeric: 'auto' });
rtf.format(-1, 'day');   // "yesterday"
rtf.format(2, 'week');   // "in 2 weeks"
rtf.format(-3, 'month'); // "3 months ago"

Custom Formatting#

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

  const tokens = {
    YYYY: date.getFullYear(),
    YY: String(date.getFullYear()).slice(-2),
    MM: pad(date.getMonth() + 1),
    M: date.getMonth() + 1,
    DD: pad(date.getDate()),
    D: date.getDate(),
    HH: pad(date.getHours()),
    H: date.getHours(),
    hh: pad(date.getHours() % 12 || 12),
    h: date.getHours() % 12 || 12,
    mm: pad(date.getMinutes()),
    m: date.getMinutes(),
    ss: pad(date.getSeconds()),
    s: date.getSeconds(),
    A: date.getHours() >= 12 ? 'PM' : 'AM',
    a: date.getHours() >= 12 ? 'pm' : 'am',
  };

  return format.replace(/YYYY|YY|MM|M|DD|D|HH|H|hh|h|mm|m|ss|s|A|a/g,
    match => tokens[match]
  );
}

formatDate(new Date(), 'YYYY-MM-DD');           // "2021-06-15"
formatDate(new Date(), 'MM/DD/YYYY');           // "06/15/2021"
formatDate(new Date(), 'HH:mm:ss');             // "14:30:00"
formatDate(new Date(), 'h:mm A');               // "2:30 PM"
formatDate(new Date(), 'YYYY-MM-DD HH:mm:ss');  // "2021-06-15 14:30:00"

Date Arithmetic#

// Add/subtract time
function addTime(date, value, unit) {
  const result = new Date(date);

  switch (unit) {
    case 'years':
      result.setFullYear(result.getFullYear() + value);
      break;
    case 'months':
      result.setMonth(result.getMonth() + value);
      break;
    case 'weeks':
      result.setDate(result.getDate() + value * 7);
      break;
    case 'days':
      result.setDate(result.getDate() + value);
      break;
    case 'hours':
      result.setHours(result.getHours() + value);
      break;
    case 'minutes':
      result.setMinutes(result.getMinutes() + value);
      break;
    case 'seconds':
      result.setSeconds(result.getSeconds() + value);
      break;
  }

  return result;
}

// Difference between dates
function dateDiff(date1, date2, unit = 'days') {
  const diff = date2.getTime() - date1.getTime();

  switch (unit) {
    case 'seconds':
      return Math.floor(diff / 1000);
    case 'minutes':
      return Math.floor(diff / (1000 * 60));
    case 'hours':
      return Math.floor(diff / (1000 * 60 * 60));
    case 'days':
      return Math.floor(diff / (1000 * 60 * 60 * 24));
    case 'weeks':
      return Math.floor(diff / (1000 * 60 * 60 * 24 * 7));
  }
}

const today = new Date();
const nextWeek = addTime(today, 1, 'weeks');
const daysDiff = dateDiff(today, nextWeek, 'days'); // 7

Date Comparison#

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

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

// Compare dates only (ignore time)
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) {
  const time = date.getTime();
  return time >= start.getTime() && time <= end.getTime();
}

// Check if date is in past/future
function isPast(date) {
  return date.getTime() < Date.now();
}

function isFuture(date) {
  return date.getTime() > Date.now();
}

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

Working with Time Zones#

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

// Format in specific timezone
function formatInTimezone(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);
}

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

// Parse date in specific timezone
function parseDateInTimezone(dateStr, timezone) {
  const date = new Date(dateStr);
  const utcDate = new Date(date.toLocaleString('en-US', { timeZone: 'UTC' }));
  const tzDate = new Date(date.toLocaleString('en-US', { timeZone: timezone }));
  const offset = utcDate.getTime() - tzDate.getTime();
  return new Date(date.getTime() + offset);
}

Common Utilities#

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

// 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, 23, 59, 59, 999);
}

// Days in month
function daysInMonth(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;
}

// Week number
function getWeekNumber(date) {
  const d = new Date(date);
  d.setHours(0, 0, 0, 0);
  d.setDate(d.getDate() + 4 - (d.getDay() || 7));
  const yearStart = new Date(d.getFullYear(), 0, 1);
  return Math.ceil((((d - yearStart) / 86400000) + 1) / 7);
}

Libraries#

// date-fns (recommended)
import { format, addDays, differenceInDays, isAfter } from 'date-fns';

format(new Date(), 'yyyy-MM-dd');
addDays(new Date(), 7);
differenceInDays(date1, date2);
isAfter(date1, date2);

// Day.js (lightweight)
import dayjs from 'dayjs';

dayjs().format('YYYY-MM-DD');
dayjs().add(7, 'day');
dayjs('2021-01-01').diff(dayjs('2021-06-15'), 'day');

// Luxon (full-featured)
import { DateTime } from 'luxon';

DateTime.now().toISO();
DateTime.now().plus({ days: 7 });
DateTime.fromISO('2021-01-01').diff(DateTime.fromISO('2021-06-15'), 'days');

Best Practices#

Parsing:
✓ Use ISO 8601 format for parsing
✓ Be explicit about timezones
✓ Validate parsed dates
✓ Handle invalid dates gracefully

Storage:
✓ Store as ISO 8601 strings or timestamps
✓ Store in UTC
✓ Convert to local time for display
✓ Use consistent formats

Display:
✓ Use Intl.DateTimeFormat for localization
✓ Consider user's timezone
✓ Use relative time when appropriate
✓ Be consistent across the app

Avoid:
✗ Parsing ambiguous date strings
✗ Mutating Date objects
✗ Ignoring timezones
✗ Manual string formatting for locales

JavaScript's Date handling has quirks like 0-indexed months and timezone complexities. Use ISO 8601 format for parsing, Intl APIs for formatting, and consider libraries like date-fns for complex operations. Always be explicit about timezones and store dates in UTC.