Problem with fromZonedTime

[ggPeti]

The docstring from fromZonedTime claims:

Returns a date instance with the UTC time of the provided date of which the values represented the local time in the time zone specified.

First of all, "of which the values represented" seems like sleazy terminology, but this may be just a wording issue. Investigating further however we find that it is not. There's a real issue with this function rendering it impractical outside of environments with UTC as the local time zone.

Let's take a look at what it does:

date-fns-tz/src/fromZonedTime/index.ts

Lines 42 to 48 in 00b48b2

	date.getFullYear(),
	date.getMonth(),
	date.getDate(),
	date.getHours(),
	date.getMinutes(),
	date.getSeconds(),
	date.getMilliseconds()

Hmm, so these are the "values". Let's check what getHours does:

The getHours() method of Date instances returns the hours for this date according to local time.

Emphasis mine. So if this function is run in an environment where Intl.DateTimeFormat().resolvedOptions().timeZone resolves to 'Etc/GMT-2', we will receive local time values in 'Etc/GMT-2' here. But alright, let's carry on, maybe this is accounted for somewhere...

but unfortunately it is not. These values are passed on to newDateUTC, which suddenly treats them as UTC values:

date-fns-tz/src/_lib/newDateUTC/index.ts

Lines 18 to 19 in 00b48b2

	utcDate.setUTCFullYear(fullYear, month, day)
	utcDate.setUTCHours(hour, minute, second, millisecond)

So we took a Date, converted it into the local time zone, then reinterpreted its parts as UTC. Mmm-hmm. This all before the real payload of the function takes place, the promised time zone based offsetting:

date-fns-tz/src/fromZonedTime/index.ts

Line 51 in 00b48b2

const offsetMilliseconds = tzParseTimezone(timeZone, new Date(utc))

Unsurprisingly, this ends up returning incorrect values unless the local time zone is UTC.

I believe the error lies in an incorrect assumption that getHours will return "the hour component from a date record". Unfortunately, this is not the case. Date objects are not records in JavaScript - the only thing they store is number of milliseconds since the epoch.

As it stands, this function can only be reasonably used in UTC environments. I believe its documentation should be updated accordingly.

[pbaern]

I encountered that problem, too, and currently decided to work around it by

import { toDate, type OptionsWithTZ } from "date-fns-tz";
// @ts-expect-error
import tzParseTimezone from "@@/node_modules/date-fns-tz/_lib/tzParseTimezone";
// @ts-expect-error
import tzPattern from "@@/node_modules/date-fns-tz/_lib/tzPattern";

export const fromZonedTime = (
  date: string | Date,
  timeZone: string,
  options?: OptionsWithTZ,
) => {
  if (typeof date === "string" && !date.match(tzPattern)) {
    return toDate(
      date,
      Object.assign(Object.assign({}, options), { timeZone }),
    );
  }
  date = toDate(date, options);
  const offsetMilliseconds = tzParseTimezone(timeZone, date);
  return new Date(date.getTime() + offsetMilliseconds);
};

export const toZonedTime = (
  date: string | Date,
  timeZone: string,
  options?: OptionsWithTZ,
) => {
  date = toDate(date, options);
  const offsetMilliseconds = tzParseTimezone(timeZone, date, true);
  return new Date(date.getTime() - offsetMilliseconds);
};