fix: formatInTimeZone around DST change

config/karma.js

@@ -160,6 +160,10 @@ function config(config) {
     reporters: getReportersConfig(),
     singleRun: !process.env.TEST_WATCH,
   })
+
+  // Run tests in specific timezone
+  // process.env.TZ = 'America/New_York';
+  // process.env.TZ = 'Asia/Shanghai';
 }
 
 function getFrameworksConfig() {

package.json

@@ -129,9 +129,11 @@
     ]
   },
   "peerDependencies": {
+    "@date-fns/utc": "^1.2.0",
     "date-fns": "^3.0.0"
   },
   "devDependencies": {
+    "@date-fns/utc": "^1.2.0",
     "@types/fs-extra": "^11.0.4",
     "@typescript-eslint/eslint-plugin": "^7.6.0",
     "@typescript-eslint/parser": "^7.6.0",

src/formatInTimeZone/index.ts

@@ -1,6 +1,8 @@
 import { format } from '../format/index.js'
 import { toZonedTime } from '../toZonedTime/index.js'
-import type { FormatOptionsWithTZ } from '../index.js'
+import { toDate, type FormatOptionsWithTZ } from '../index.js'
+import { tzParseTimezone } from '../_lib/tzParseTimezone/index.js'
+import { UTCDate } from '@date-fns/utc'
 
 /**
  * @name formatInTimeZone
@@ -23,7 +25,7 @@ import type { FormatOptionsWithTZ } from '../index.js'
  *   (`yy`, `yyyy`). See: https://git.io/fxCyr
  * @param {String} [options.timeZone=''] - used to specify the IANA time zone offset of a date String.
  */
-export function formatInTimeZone(
+export function formatInTimeZone0(
   date: Date | string | number,
   timeZone: string,
   formatStr: string,
@@ -36,3 +38,25 @@ export function formatInTimeZone(
   }
   return format(toZonedTime(date, timeZone, { timeZone: options.timeZone }), formatStr, options)
 }
+
+export function formatInTimeZoneDSTFriendly(
+  date: Date | string | number,
+  timeZone: string,
+  formatStr: string,
+  options?: FormatOptionsWithTZ
+): string {
+  options = {
+    ...options,
+    timeZone,
+    originalDate: date,
+  }
+  date = toDate(date, options)
+
+  const offsetMilliseconds = tzParseTimezone(timeZone, date, true)
+
+  // replaces toZonedTime with UTCDate
+  const d = new UTCDate(date.getTime() - offsetMilliseconds)
+
+  return format(d, formatStr, options)
+}
+export const formatInTimeZone = formatInTimeZoneDSTFriendly

src/formatInTimeZone/test.js

@@ -1,6 +1,7 @@
 import assert from 'power-assert'
 import { enGB } from 'date-fns/locale/en-GB'
 import { formatInTimeZone } from './index.js'
+import { toZonedTime } from '../toZonedTime/index.js'
 
 describe('formatInTimeZone', function () {
   it('treat date only string in the timezone specified in the options', function () {
@@ -115,4 +116,43 @@ describe('formatInTimeZone', function () {
       RangeError
     )
   })
+
+  describe('format of utc time that crosses dst', function () {
+    it('UTC before DST changeover - hour only', function () {
+      var date = '2024-03-09T02:00:00.000Z'
+      var timeZone = 'UTC'
+      var format = 'h:mm aaaa'
+      var expected = '2:00 a.m.'
+      assert.equal(formatInTimeZone(date, timeZone, format), expected)
+    })
+
+    // https://github.com/marnusw/date-fns-tz/issues/252
+    // https://github.com/marnusw/date-fns-tz/issues/178
+    it('UTC on DST changeover - hour only', function () {
+      var date = '2024-03-10T02:00:00.000Z'
+      var timeZone = 'UTC'
+      var format = 'h:mm aaaa'
+      var expected = '2:00 a.m.'
+      assert.equal(formatInTimeZone(date, timeZone, format), expected)
+    })
+
+    // test cases from: https://github.com/marnusw/date-fns-tz/issues/258#issue-2000115019
+    it('UTC before DST changeover', function () {
+      var result = formatInTimeZone(new Date('2023-03-12T01:05Z'), 'UTC', 'Pp z')
+      var expected = '03/12/2023, 1:05 AM UTC'
+      assert.equal(result, expected)
+    })
+
+    it('UTC on DST changeover', function () {
+      var result = formatInTimeZone(new Date('2023-03-12T02:05Z'), 'UTC', 'Pp z')
+      var expected = '03/12/2023, 2:05 AM UTC'
+      assert.equal(result, expected)
+    })
+
+    it('UTC after DST changeover', function () {
+      var result = formatInTimeZone(new Date('2023-03-12T03:05Z'), 'UTC', 'Pp z')
+      var expected = '03/12/2023, 3:05 AM UTC'
+      assert.equal(result, expected)
+    })
+  })
 })