dotiw 5.6.0 → 5.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b9778f6b8dfb3fa5013f9e365c91be2fcb955f040e19dde50d8f70b1fb28fcd
-  data.tar.gz: 5213a53264dd238ea225939d53c40a63523749b92331ef4a899fa3ca190d5bce
+  metadata.gz: fa29e6fb27292383b6c52e90e638a79df342e512d2132fc43399fbdac2accce7
+  data.tar.gz: a2a5f6a9f954ffa985ecb48a5888f860191be892e451f5a25726d9c7e7bb58d2
 SHA512:
-  metadata.gz: 2efac079381c10ed7584f921dbeab2c3b4ae96f63a4b32c470a986a2a521f0a91c94e26871e92bcdcd9718d05d2bb6c41bc051155868b9c3684695b5b662d27e
-  data.tar.gz: 1506fe3f4715fd1f85b72d8de416d4dfdff144e02bce2837c741ab82d7928b2fed38e6c08fac19e1a5a0e155a9ec4c947407d1878107e5c15cc7947618f731dd
+  metadata.gz: d95cc6198e93afadd8a16b09125166a1b0a8474c21f44cb194ae1e77e0a1cfa2a1e35c2a752bf275b16c7d0ec54144d99c3a2940865db373f80d0b3668c77a39
+  data.tar.gz: 00cdcea3f7f60fed460de3992568f7bce85c680212cac766a55a2186782fa9e76d578326f4af29bee6dc877fd614fb875ed5430e9288be18209be0ac17638155

data/CHANGELOG.md

@@ -1,4 +1,11 @@
-## 5.6.0 (2026/8/28)
+## 5.6.1 (2026/09/09)
+
+* [#160](https://github.com/radar/distance_of_time_in_words/issues/160): Fix `offset_delta` incorrectly folding the full UTC offset difference into the distance when comparing timestamps with different, unrelated offsets (e.g. one in UTC, one with an explicit `-08:00` offset) instead of only when they're the same clock across a real DST/tzdata transition - [@dblock](https://github.com/dblock).
+* [#162](https://github.com/radar/distance_of_time_in_words/issues/162): Fix `same_clock?` incorrectly treating two `Time` values converted from `ActiveSupport::TimeWithZone` in different zones as the same clock on Rails >= 8.0, where `#to_time` returns a `Time` whose `#zone` is the `ActiveSupport::TimeZone` object itself rather than a `nil`/String abbreviation - [@dblock](https://github.com/dblock).
+* [#165](https://github.com/radar/distance_of_time_in_words/issues/165): Fix `offset_delta` folding the full UTC offset change into the top-level distance, which could overcorrect past zero and report "less than 1 second" for a case where a small real elapsed time (e.g. 1 minute) crosses a much larger DST transition (e.g. Europe/Dublin's 1 hour fall-back) - the offset correction is now only applied to the sub-day leftover once the distance has already been split into calendar fields - [@dblock](https://github.com/dblock).
+* [#170](https://github.com/radar/distance_of_time_in_words/issues/170): Fix `distance_of_time_in_words` unnecessarily converting an `ActiveSupport::TimeWithZone` argument to a plain `Time` via `#to_time`, which discarded its real zone on Rails < 8.0 and prevented `same_clock?` from correctly folding in a historical UTC offset change (e.g. Pacific/Norfolk's 2015 offset change, #153) on those versions - [@dblock](https://github.com/dblock).
+
+## 5.6.0 (2026/08/28)
 
 * [#145](https://github.com/radar/distance_of_time_in_words/pull/145): Add `dotiw/core` require path to use dotiw without overriding the Rails date helpers, `DOTIW.distance_of_time_in_words` shortcut - [@ermolaev](https://github.com/ermolaev).
 * [#146](https://github.com/radar/distance_of_time_in_words/pull/146): Add support for Rails 8 - [@dblock](https://github.com/dblock).

data/lib/dotiw/methods.rb

@@ -5,8 +5,8 @@ module DOTIW
     extend self
 
     def distance_of_time_in_words_hash(from_time, to_time, options = {})
-      from_time = from_time.to_time if !from_time.is_a?(Time) && from_time.respond_to?(:to_time)
-      to_time = to_time.to_time if !to_time.is_a?(Time) && to_time.respond_to?(:to_time)
+      from_time = coerce_to_time(from_time)
+      to_time = coerce_to_time(to_time)
 
       DOTIW::TimeHash.new(nil, from_time, to_time, options).to_hash
     end
@@ -73,12 +73,28 @@ module DOTIW
       if value.is_a?(Numeric)
         Time.at(value)
       elsif value.respond_to?(:to_time)
-        value.to_time
+        coerce_to_time(value)
       else
         raise ArgumentError, "#{value.inspect} can't be converted to a Time value"
       end
     end
 
+    # An ActiveSupport::TimeWithZone already carries its zone explicitly and
+    # supports every operation TimeHash needs (arithmetic, #advance, calendar
+    # accessors, #utc_offset), so there's no reason to convert it to a plain
+    # Time first. Doing so is actively harmful: on Rails < 8.0 (before
+    # to_time_preserves_timezone defaulted to :zone), TimeWithZone#to_time
+    # discards the real zone and returns a Time in the process's local zone
+    # instead, which loses the information TimeHash's same_clock? needs to
+    # correctly fold a historical UTC offset change into the distance
+    # (#153/#162/#165) on Rails < 8.0 (#170) - the loss isn't inherent to
+    # older Rails, it's an unforced conversion we don't need to make.
+    def coerce_to_time(value)
+      return value if value.is_a?(Time) || value.respond_to?(:time_zone)
+
+      value.to_time
+    end
+
     def options_with_scope(options)
       if options.key?(:compact)
         options.merge(scope: DOTIW::DEFAULT_I18N_SCOPE_COMPACT)

data/lib/dotiw/time_hash.rb

@@ -11,11 +11,9 @@ module DOTIW
       @options    = options.dup
       @distance   = distance
       @from_time  = from_time || Time.current
-      @to_time    = to_time   || (@to_time_not_given = true && @from_time + distance.seconds)
+      @to_time    = to_time || (@from_time + distance.seconds)
       @smallest, @largest = [@from_time, @to_time].minmax
-      @to_time += offset_delta(smallest, largest) if @to_time_not_given
-      @smallest, @largest = [@from_time, @to_time].minmax
-      @distance ||= (largest - smallest) + offset_delta(smallest, largest)
+      @distance ||= largest - smallest
 
       build_time_hash
     end
@@ -38,14 +36,56 @@ module DOTIW
     # reflects any change in UTC offset between them (whether from a DST
     # transition or a permanent tzdata rule change, e.g. Pacific/Norfolk's
     # 2015 UTC offset change), which is what we want when reporting a raw
-    # elapsed duration. However, when we split that distance into calendar
-    # fields (years/months/weeks/days), we want the offset difference
-    # folded away so the leftover hours/minutes/seconds reflect only actual
-    # elapsed wall-clock time, not artifacts of an offset shift.
+    # elapsed duration - this is why we never touch the top-level @distance
+    # used to pick which build_* branch to use. However, once we've split
+    # that distance into calendar fields (years/months/weeks/days, #153),
+    # we want the offset difference folded out of the *sub-day leftover*
+    # only, so it reflects actual elapsed wall-clock time rather than an
+    # artifact of an offset shift, without risking flipping the sign of the
+    # much larger top-level distance the way applying this correction
+    # globally used to (#165).
+    #
+    # This only makes sense when both times are the same clock (the same
+    # location/zone before and after a transition). If they're simply
+    # expressed with different, unrelated UTC offsets (e.g. one in UTC and
+    # one with an explicit "-08:00" offset), any difference between their
+    # offsets is an artifact of how each was represented, not a transition,
+    # and folding it in would double count what subtraction already got
+    # right (#160).
     def offset_delta(smallest, largest)
+      return 0 unless same_clock?(smallest, largest)
+
       largest.utc_offset - smallest.utc_offset
     end
 
+    # Whether smallest and largest are readings of the same underlying
+    # clock, as opposed to two independently fixed offsets that simply
+    # happen to differ (e.g. one in UTC, one with an explicit "-08:00").
+    # Only in the former case does a UTC offset difference represent a
+    # real transition (DST, or a historical tzdata rule change) rather
+    # than an artifact of how each time happens to be represented.
+    #
+    # An ActiveSupport::TimeWithZone carries its zone explicitly, so two
+    # of them share a clock when their +time_zone+ matches. A plain Ruby
+    # Time normally reports its zone as a String abbreviation (e.g. "PST")
+    # or +nil+ (fixed numeric offset, which can never transition, so two
+    # such times can't share a clock). Depending on the Ruby/ActiveSupport
+    # version, however, converting an ActiveSupport::TimeWithZone via
+    # +#to_time+ can instead produce a plain Time whose +#zone+ is the
+    # ActiveSupport::TimeZone object itself (#162) - in that case we
+    # compare the zone objects directly rather than assuming any two
+    # non-String zones both refer to the process's system zone.
+    def same_clock?(smallest, largest)
+      if smallest.respond_to?(:time_zone) || largest.respond_to?(:time_zone)
+        smallest.respond_to?(:time_zone) && largest.respond_to?(:time_zone) &&
+          smallest.time_zone == largest.time_zone
+      elsif !smallest.zone.is_a?(String) || !largest.zone.is_a?(String)
+        !smallest.zone.nil? && smallest.zone == largest.zone
+      else
+        !smallest.zone.nil? && !smallest.utc? && !largest.zone.nil? && !largest.utc?
+      end
+    end
+
     def build_time_hash
       if (max_unit = options[:max_unit])
         build_max_unit(max_unit.to_sym)
@@ -191,9 +231,28 @@ module DOTIW
       output[:weeks]   = weeks
       output[:days]    = days
 
-      total_days, @distance = distance.abs.divmod(ONE_DAY.to_i)
-
-      [total_days, @distance]
+      # total_days is discarded: years/months/weeks/days above are derived
+      # from calendar components (largest/smallest year/month/day), an
+      # entirely separate calculation from @distance. All we need from here
+      # on is the leftover below the day boundary, which is just @distance
+      # mod one day - decoupled like this (rather than reconstructed by
+      # advancing smallest by years/months/weeks/days and diffing against
+      # largest) so a calendar edge case where that reconstruction doesn't
+      # land exactly on largest (e.g. Jan 31 -> Mar 2) can never leave a
+      # leftover large enough to loop back into this same branch forever.
+      # We do fold in any UTC offset change between smallest and largest
+      # (#153) exactly once - guarded, since build_years and build_months
+      # both call this method unconditionally, and accumulate_on: :years
+      # ends up invoking it twice (once via build_years, once via
+      # build_months) - but only here, not in the top-level @distance used
+      # to pick which build_* branch to use in the first place, so a real
+      # elapsed time much smaller than the offset change (#165) still gets
+      # bucketed correctly.
+      unless @offset_applied
+        @offset_applied = true
+        @distance = distance.abs + offset_delta(smallest, largest)
+      end
+      _total_days, @distance = distance.abs.divmod(ONE_DAY.to_i)
     end
   end
 end

data/lib/dotiw/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DOTIW
-  VERSION = '5.6.0'
+  VERSION = '5.6.1'
 end

data/spec/lib/dotiw_spec.rb

@@ -254,6 +254,110 @@ describe 'A better distance_of_time_in_words' do
       end
     end
 
+    context 'with different UTC offsets that are not the same clock (#160)' do
+      # Real, non-mocked reproduction from #160: comparing two timestamps
+      # expressed with different, unrelated UTC offsets (not the same
+      # location before/after a real transition) incorrectly folded the
+      # full offset difference between them into the reported distance.
+      # Neither endpoint here crosses any DST or historical offset
+      # transition; only their representation differs.
+      it 'is 1 hour, not 9 hours' do
+        from = Time.new(2026, 1, 15, 11, 0, 0, '-08:00')
+        to = Time.utc(2026, 1, 15, 20)
+
+        expect(to - from).to eq(3600.0)
+        expect(distance_of_time_in_words(from, to)).to eq('1 hour')
+      end
+
+      it 'is still 1 hour when both timestamps are in UTC' do
+        from = Time.new(2026, 1, 15, 11, 0, 0, '-08:00').getutc
+        to = Time.utc(2026, 1, 15, 20)
+
+        expect(distance_of_time_in_words(from, to)).to eq('1 hour')
+      end
+    end
+
+    context 'with Time values using different zone objects (#162)' do
+      # #to_time on an ActiveSupport::TimeWithZone (with to_time_preserves_timezone
+      # set, the default since Rails 7.1) returns a plain Time whose #zone is the
+      # ActiveSupport::TimeZone object itself, not a String abbreviation. Building
+      # these directly via TimeZone#local/#to_time, rather than Ruby's Time.new(in:)
+      # keyword (only available on Ruby 3.2+), reproduces the same shape of object
+      # portably across the whole supported Ruby/Rails matrix.
+      it 'treats different TimeZone-object zones as different clocks, without folding in any offset' do
+        tokyo_time = ActiveSupport::TimeZone['Asia/Tokyo'].local(2026, 1, 16, 4, 0, 0).to_time
+        la_time = ActiveSupport::TimeZone['America/Los_Angeles'].local(2026, 1, 15, 12, 0, 0).to_time
+
+        expect(la_time - tokyo_time).to eq(3600.0)
+        expect(distance_of_time_in_words(tokyo_time, la_time)).to eq('1 hour')
+      end
+
+      # Same TimeZone-object shape as above, but far enough apart to be split
+      # into calendar fields (years/months/weeks/days, #153/#165), which is
+      # the only place same_clock? is invoked (see #165). Tokyo and LA are
+      # unrelated zones (not the same clock before/after a transition), so
+      # this exercises same_clock?'s "not a String zone" comparison finding
+      # the two TimeZone objects unequal, exactly like the #160 case does
+      # for String zones.
+      it 'treats TimeZone-object zones far enough apart to span calendar fields as different clocks' do
+        tokyo_time = ActiveSupport::TimeZone['Asia/Tokyo'].local(2025, 1, 16, 4, 0, 0).to_time
+        la_time = ActiveSupport::TimeZone['America/Los_Angeles'].local(2026, 3, 15, 12, 0, 0).to_time
+
+        expect(distance_of_time_in_words(tokyo_time, la_time, true)).to eq('1 year, 1 month, 3 weeks, and 6 days')
+      end
+    end
+
+    context 'with explicit named zones' do
+      # https://github.com/moment/luxon/blob/3.7.2/test/datetime/diff.test.js#L317-L330
+      it 'preserves the elapsed time between UTC and CEST' do
+        from = Time.utc(2022, 5, 5, 23, 0, 0)
+        to = Time.new(2022, 5, 10, 0, 0, 0, '+02:00')
+
+        expect(to - from).to eq(3.days + 23.hours)
+        expect(distance_of_time_in_words(from, to, true)).to eq('3 days and 23 hours')
+      end
+
+      # https://github.com/bitwalker/timex/blob/3.7.11/test/format_duration_humanized_test.exs
+      it 'preserves one minute across the Europe/Dublin DST fall-back (#165)' do
+        # Passing an ActiveSupport::TimeWithZone straight through (rather than
+        # calling #to_time on it, as in the #162 example above) exercises the
+        # same_clock? branch that compares #time_zone directly. Prior to the
+        # #165 fix, dotiw unconditionally called #to_time on any TimeWithZone
+        # argument, which discarded the real zone entirely on Rails < 8.0 (see
+        # DOTIW::Methods#coerce_to_time, #170) - so this was only reproducible
+        # on Rails >= 8.0, and passed for the wrong reason everywhere else. Now
+        # that #coerce_to_time no longer makes that unforced conversion, and
+        # offset_delta is only ever applied to the sub-day leftover rather
+        # than the top-level distance, this passes for the right reason on
+        # every supported Rails version.
+        dublin = ActiveSupport::TimeZone['Europe/Dublin']
+        from = Time.utc(2024, 10, 27, 0, 59, 30).in_time_zone(dublin)
+        to = from + 1.minute
+
+        expect(from.utc_offset).to eq(1.hour)
+        expect(to.utc_offset).to eq(0)
+        expect(to - from).to eq(1.minute)
+        expect(distance_of_time_in_words(from, to)).to eq('1 minute')
+      end
+
+      # https://github.com/dblock/tz_test/blob/master/ruby/test.rb
+      it 'folds the Pacific/Norfolk historical offset change into the calendar distance' do
+        # As with the Dublin example above, from/to are passed through as
+        # ActiveSupport::TimeWithZone rather than being converted with
+        # #to_time, so their real zone is preserved on every Rails version
+        # (see DOTIW::Methods#coerce_to_time, #170) and same_clock? can
+        # correctly recognize this as the same clock across Pacific/Norfolk's
+        # 2015 historical UTC offset change.
+        norfolk = ActiveSupport::TimeZone['Pacific/Norfolk']
+        from = norfolk.local(2015, 1, 15)
+        to = norfolk.local(2016, 3, 15)
+
+        expect(from.utc_offset).to eq(11.hours + 30.minutes)
+        expect(to.utc_offset).to eq(11.hours)
+        expect(distance_of_time_in_words(from, to, true)).to eq('1 year and 2 months')
+      end
+    end
+
     describe 'accumulate_on:' do
       [
         [START_TIME,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dotiw
 version: !ruby/object:Gem::Version
-  version: 5.6.0
+  version: 5.6.1
 platform: ruby
 authors:
 - Ryan Bigg
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-28 00:00:00.000000000 Z
+date: 2026-09-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport