Skip to main content

TypeScript Date Handling Guide

When working with dates in TypeScript, developers often face challenges due to the complexities of date manipulation and formatting. The native date type in JavaScript provides methods for basic operations, but it requires careful implementation to handle time zones, formatting, and calculations correctly. In this guide, we'll cover the key aspects of date handling in TypeScript, from basic operations to advanced techniques. By the end, you'll have the knowledge to manage common date-related tasks in your TypeScript projects.

Formatting a Date Object​

You can format a date object in TypeScript using built-in methods of the Date object. The date format options range from simple to highly customizable outputs.

const date = new Date();
console.log(date.toISOString()); // Output: "2024-09-16T14:30:00.000Z"
console.log(date.toLocaleString()); // Output: "9/16/2024, 2:30:00 PM"

When working with Convex, these formatting techniques help display dates consistently in your application's user interface.

Converting a Date to a String​

To convert a Date object to a string with a specific format, you can use the date format methods like getFullYear(), getMonth(), and getDate() to extract individual components and build a custom string.

function formatDate(date: Date): string {
  const year = date.getFullYear();
  const month = (date.getMonth() + 1).toString().padStart(2, '0');
  const day = date.getDate().toString().padStart(2, '0');
  return `${year}-${month}-${day}`;
}

const date = new Date();
console.log(formatDate(date)); // Output: "2024-09-16"

You can also add time components for more detailed formatting:

function formatDateWithTime(date: Date): string {
  const year = date.getFullYear();
  const month = (date.getMonth() + 1).toString().padStart(2, '0');
  const day = date.getDate().toString().padStart(2, '0');
  const hours = date.getHours().toString().padStart(2, '0');
  const minutes = date.getMinutes().toString().padStart(2, '0');
  
  return `${year}-${month}-${day} ${hours}:${minutes}`;
}

console.log(formatDateWithTime(new Date())); // Output: "2024-09-16 14:30"

For applications requiring complex filtering, properly formatted date strings can help with date-based queries and comparisons.

Calculating the Difference Between Two Dates​

To find the difference between two Date objects, subtract their timestamps.

function calculateDateDifference(date1: Date, date2: Date): number {
  const timestamp1 = date1.getTime();
  const timestamp2 = date2.getTime();
  return Math.abs(timestamp2 - timestamp1);
}

const date1 = new Date('2024-09-16');
const date2 = new Date('2024-09-20');
console.log(calculateDateDifference(date1, date2)); // Output: 345600000

To calculate the difference in days, divide the result by the number of milliseconds in a day.

function calculateDateDifferenceInDays(date1: Date, date2: Date): number {
  const differenceInMilliseconds = calculateDateDifference(date1, date2);
  return Math.round(differenceInMilliseconds / (1000 * 60 * 60 * 24));
}

const date1 = new Date('2024-09-16');
const date2 = new Date('2024-09-20');
console.log(calculateDateDifferenceInDays(date1, date2)); // Output: 4

When building applications with TypeScript on Convex, these functions help create reliable date comparisons and calculations.

Creating a Date Object from a Timestamp​

To create a Date object from a timestamp (milliseconds since January 1, 1970), use the Date constructor.

const timestamp = 1694913600000;
const date = new Date(timestamp);
console.log(date); // Output: "2024-09-16T14:30:00.000Z"

You can also convert a string to number and use it as a timestamp:

const dateString = "1694913600000";
const timestamp = parseInt(dateString, 10);
const date = new Date(timestamp);
console.log(date); // Output: "2024-09-16T14:30:00.000Z"

This method is useful when retrieving timestamps from server responses or databases in your TypeScript applications.

Adding or Subtracting Days from a Date Object​

To add or subtract days from a Date object, get the timestamp of the date, adjust it by the required number of milliseconds, and create a new Date object from it.

function addDays(date: Date, days: number): Date {
  const timestamp = date.getTime();
  const updatedTimestamp = timestamp + days * 24 * 60 * 60 * 1000;
  return new Date(updatedTimestamp);
}

const date = new Date('2024-09-16');
const updatedDate = addDays(date, 5);
console.log(updatedDate); // Output: "2024-09-21T00:00:00.000Z"

Similarly, to subtract days, use a negative value:

function subtractDays(date: Date, days: number): Date {
  return addDays(date, -days);
}

const date = new Date('2024-09-16');
const earlierDate = subtractDays(date, 3);
console.log(earlierDate); // Output: "2024-09-13T00:00:00.000Z"

When working with complex data operations in TypeScript, these helper functions can simplify date manipulations in your code.

Handling Time Zones with Date Objects​

TypeScript's Date object works in the local time zone of the environment. To handle time zones, use getTimezoneOffset() to find the offset from UTC.

const date = new Date();
const timezoneOffset = date.getTimezoneOffset();
console.log(timezoneOffset); // Output: -300 (for UTC-5)

To convert a Date object to a different time zone, adjust its timestamp by the target time zone offset.

function convertToTimezone(date: Date, targetOffsetMinutes: number): Date {
  // Get the current timezone offset
  const currentOffset = date.getTimezoneOffset();
  
  // Calculate the difference between current and target offsets
  const offsetDifference = currentOffset - targetOffsetMinutes;
  
  // Create a new date adjusted for the target timezone
  const newDate = new Date(date.getTime() + offsetDifference * 60 * 1000);
  return newDate;
}

const date = new Date();
// Convert to UTC+1 (60 minutes behind UTC)
const dateInUTCPlus1 = convertToTimezone(date, -60);
console.log(dateInUTCPlus1);

For TypeScript applications with global users, proper time zone handling ensures consistent date experiences across regions. The date type provides these essential methods for timezone calculations.

Comparing Two Date Objects for Equality​

To check if two Date objects are equal, compare their timestamps.

function areDatesEqual(date1: Date, date2: Date): boolean {
  return date1.getTime() === date2.getTime();
}


const date1 = new Date('2024-09-16T14:30:00.000Z');
const date2 = new Date('2024-09-16T14:30:00.000Z');
console.log(areDatesEqual(date1, date2)); // Output: true

You can also compare dates to determine their order:

function compareDates(date1: Date, date2: Date): number {
  // Returns -1 if date1 is earlier, 0 if equal, 1 if date1 is later
  const timestamp1 = date1.getTime();
  const timestamp2 = date2.getTime();
  
  if (timestamp1 < timestamp2) return -1;
  if (timestamp1 > timestamp2) return 1;
  return 0;
}

const earlier = new Date('2024-09-15');
const later = new Date('2024-09-20');
console.log(compareDates(earlier, later)); // Output: -1
console.log(compareDates(later, earlier)); // Output: 1

This comparison approach works well in complex filtering scenarios where you need to sort or filter items based on dates in arrays of objects.

Final Thoughts on Handling Dates in TypeScript​

Working with dates in TypeScript builds on JavaScript's native Date object. The examples in this guide should help you handle common date operations. Remember to account for time zones when working with international applications, and consider creating reusable date utilities for your projects.