Understanding MomentJS and JavaScript Date Handling: UTC Time vs Local Time Conversion Mechanisms

The Nature of Timestamps and Timezone Representation

When handling dates and times in JavaScript and MomentJS, understanding the relationship between timestamps and timezones is crucial. A timestamp is essentially a numerical value representing a specific point in time, typically measured in milliseconds since the Unix epoch (January 1, 1970, 00:00:00 UTC). This value is absolute and unique, independent of any timezone settings. However, when this point in time is presented as a human-readable string, timezone offsets come into play, causing the same point in time to display different "hour values" across different timezones.

UTC and Local Time Operations in MomentJS

MomentJS provides powerful tools for timezone conversion. The moment.utc() method creates a Moment object based on Coordinated Universal Time (UTC), while moment() defaults to the local timezone. The following code example demonstrates how to correctly obtain and compare UTC time:

var moment = require('moment');

var localDate = new Date();
var localMoment = moment();
var utcMoment = moment.utc();
var utcDate = new Date(utcMoment.format());

// Same millisecond values indicate the same point in time
console.log('localData unix = ' + localDate.valueOf());
console.log('localMoment unix = ' + localMoment.valueOf());
console.log('utcMoment unix = ' + utcMoment.valueOf());

// Formatted strings differ due to timezone
console.log('localDate = ' + localDate);
console.log('localMoment string = ' + localMoment.format());
console.log('utcMoment string = ' + utcMoment.format());
console.log('utcDate  = ' + utcDate);

// Convert local time to UTC format
console.log('localDate as UTC format = ' + moment.utc(localDate).format());
console.log('localDate as UTC unix = ' + moment.utc(localDate).valueOf());

Running this code will output results similar to the following, clearly showing differences in representation for the same point in time:

localData unix = 1415806206570
localMoment unix = 1415806206570
utcMoment unix = 1415806206570
localDate = Wed Nov 12 2014 10:30:06 GMT-0500 (EST)
localMoment string = 2014-11-12T10:30:06-05:00
utcMoment string = 2014-11-12T15:30:06+00:00
utcDate  = Wed Nov 12 2014 10:30:06 GMT-0500 (EST)
localDate as UTC format = 2014-11-12T15:30:06+00:00
localDate as UTC unix = 1415806206570

Solving MongoDB Date Storage Issues

Addressing the original question's requirement for MongoDB date storage, the key is to ensure timestamps are based on UTC. MongoDB's Date type expects UTC time; passing local time strings may cause timezone offset errors. The correct approach is to use moment.utc().toDate() to obtain a JavaScript Date object, which internally stores UTC time. However, note that when calling the toString() method, the Date object converts to a local time string, which can be confusing.

A more reliable method is to directly store millisecond timestamps or UTC strings in ISO 8601 format. For example:

// Method 1: Store millisecond timestamp
var utcTimestamp = moment.utc().valueOf();
// Method 2: Store ISO format UTC string
var utcISOString = moment.utc().format();

When reading from the database, parse using moment.utc(timestamp) or moment.utc(isoString) to ensure subsequent operations are based on UTC time.

Best Practices for Time Comparison and Operations

For time comparisons, it is recommended to always use millisecond values, as they are timezone-agnostic absolute quantities. For example:

var time1 = moment.utc('2023-01-01T00:00:00Z').valueOf();
var time2 = moment('2023-01-01T00:00:00-05:00').valueOf();
if (time1 === time2) {
    console.log('Same point in time');
}

If calendar-based operations (such as comparing days or hours) are needed, first convert the time to UTC:

var localMoment = moment('2023-01-01T20:00:00-05:00');
var utcMoment = moment.utc(localMoment);
console.log(utcMoment.hour()); // Outputs UTC hour

By adhering to these principles, developers can avoid common timezone pitfalls and ensure consistent application behavior across different environments.