dotiw 5.5.0 → 5.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 32864f97b3b06dc77f8c793e11a5b17b1d2af506bdfac0c559354f3e4eef7998
-  data.tar.gz: 20efed42fb0802a836f078f2791d78e7b863005b73780243ad4867bbf653103e
+  metadata.gz: 1b9778f6b8dfb3fa5013f9e365c91be2fcb955f040e19dde50d8f70b1fb28fcd
+  data.tar.gz: 5213a53264dd238ea225939d53c40a63523749b92331ef4a899fa3ca190d5bce
 SHA512:
-  metadata.gz: 6bb97a0d7bc860b57432dc81cb3d8a7921c6364c5271db648d30984164f26d6f4003e21de28252f958294960df1b0270cc4fbf83ae7602be23096829404ee2fe
-  data.tar.gz: e2d4f70428937b7e5c409666612dd7aefbe63e71d884a3738b240c222fc2f36a8df7a66b83fa4d52fef96cd27e7edd3a9fdecb15e497fa46853e9b3922f83663
+  metadata.gz: 2efac079381c10ed7584f921dbeab2c3b4ae96f63a4b32c470a986a2a521f0a91c94e26871e92bcdcd9718d05d2bb6c41bc051155868b9c3684695b5b662d27e
+  data.tar.gz: 1506fe3f4715fd1f85b72d8de416d4dfdff144e02bce2837c741ab82d7928b2fed38e6c08fac19e1a5a0e155a9ec4c947407d1878107e5c15cc7947618f731dd

data/.github/workflows/ruby.yml

@@ -9,26 +9,33 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - ruby-version: 3.4
-          - ruby-version: 3.3
-          - ruby-version: 3.2
-          - ruby-version: 3.1
-          - ruby-version: 3.0
-          - ruby-version: 2.7
-          - ruby-version: 2.7
+          - ruby-version: '4.0'
+          - ruby-version: '3.4'
+          - ruby-version: '3.3'
+          - ruby-version: '3.2'
+          - ruby-version: '3.1'
+          - ruby-version: '3.0'
+          - ruby-version: '2.7'
+          - ruby-version: '2.7'
             gemfile: gemfiles/rails_5.0.gemfile
-          - ruby-version: 2.7
+          - ruby-version: '2.7'
             gemfile: gemfiles/rails_5.1.gemfile
-          - ruby-version: 2.7
+          - ruby-version: '2.7'
             gemfile: gemfiles/rails_5.2.gemfile
-          - ruby-version: 3.4
+          - ruby-version: '3.4'
             gemfile: gemfiles/rails_6.0.gemfile
-          - ruby-version: 3.4
+          - ruby-version: '3.4'
             gemfile: gemfiles/rails_7.0.gemfile
-          - ruby-version: 3.4
+          - ruby-version: '3.4'
             gemfile: gemfiles/rails_7.1.gemfile
-          - ruby-version: 3.4
+          - ruby-version: '3.4'
             gemfile: gemfiles/rails_7.2.gemfile
+          - ruby-version: '3.4'
+            gemfile: gemfiles/rails_8.0.gemfile
+          - ruby-version: '3.4'
+            gemfile: gemfiles/rails_8.1.gemfile
+          - ruby-version: '3.4'
+            gemfile: gemfiles/rails_8.1_i18n.gemfile
     steps:
       - uses: actions/checkout@v2
       - name: Set up Ruby
@@ -44,3 +51,20 @@ jobs:
           gem install bundler -v ${BUNDLER:-2.1.4}
           bundle install --jobs 4 --retry 3
           bundle exec rake
+      - name: Upload coverage to Coveralls
+        if: matrix.ruby-version == '3.4'
+        uses: coverallsapp/github-action@v2
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          flag-name: ruby-${{ matrix.ruby-version }}-${{ matrix.gemfile }}
+          parallel: true
+
+  finish:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Close parallel build
+        uses: coverallsapp/github-action@v2
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          parallel-finished: true

data/.gitignore

@@ -1,5 +1,6 @@
 tmp
 pkg
+coverage
 spec/fixtures/database.yml
 .rvmrc
 Gemfile.lock

data/Appraisals

@@ -25,3 +25,16 @@ end
 appraise 'rails_7.2' do
   gem 'rails', '~> 7.2.0'
 end
+
+appraise 'rails_8.0' do
+  gem 'rails', '~> 8.0.0'
+end
+
+appraise 'rails_8.1' do
+  gem 'rails', '~> 8.1.0'
+end
+
+appraise 'rails_8.1_i18n' do
+  gem 'rails', '~> 8.1.0'
+  gem 'rails-i18n'
+end

data/CHANGELOG.md

@@ -1,12 +1,28 @@
-## 5.4.0 (Next)
+## 5.6.0 (2026/8/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).
+* [#147](https://github.com/radar/distance_of_time_in_words/pull/147): Add support for Rails 8.1, drop the `tzinfo ~> 1.2.7` development pin - [@ermolaev](https://github.com/ermolaev).
+* [#148](https://github.com/radar/distance_of_time_in_words/pull/148): Add `max_unit` option to express the entire distance as a single number in one unit - [@dblock](https://github.com/dblock).
+* [#79](https://github.com/radar/distance_of_time_in_words/issues/79): Speed up `distance_of_time_in_words` by avoiding `I18n.with_options`/`ActiveSupport::OptionMerger` allocation for translations, using `I18n.translate` directly instead - [@dblock](https://github.com/dblock).
+* [#77](https://github.com/radar/distance_of_time_in_words/issues/77), [#120](https://github.com/radar/distance_of_time_in_words/issues/120): Fix `only`/`except` discarding the duration of excluded fractions instead of folding them into the next smaller included fraction - [@dblock](https://github.com/dblock).
+* [#63](https://github.com/radar/distance_of_time_in_words/issues/63): Fix incorrect DST correction in timezones with an inverted DST scheme (e.g. Europe/Dublin) by comparing `utc_offset` instead of the unreliable `Time#dst?` - [@dblock](https://github.com/dblock).
+* [#153](https://github.com/radar/distance_of_time_in_words/issues/153): Fix leftover hours/minutes leaking a historical UTC offset change (e.g. Pacific/Norfolk's 2015 offset change) into the result instead of folding it into the calendar distance - [@dblock](https://github.com/dblock).
+* [#44](https://github.com/radar/distance_of_time_in_words/issues/44): Document that `vague: true` combined with a non-English `locale:` requires the host application to load Rails' own translations for that locale - [@dblock](https://github.com/dblock).
+* [#156](https://github.com/radar/distance_of_time_in_words/pull/156): Add Ruby 4.0 to the test matrix - [@dblock](https://github.com/dblock).
+* [#158](https://github.com/radar/distance_of_time_in_words/pull/158): Add test coverage reporting with SimpleCov and Coveralls, merged across all Ruby 3.4 CI jobs (default + pinned Rails gemfiles) using parallel builds - [@dblock](https://github.com/dblock).
+
+## 5.5.0 (2026/03/15)
 
 * [#131](https://github.com/radar/distance_of_time_in_words/pull/131): Deprecates `highest_measure_only`. Adds alternate form of `highest_measures` option to permit rounding up whatever part of the duration was previously silently discarded - [@seansfkelley](https://github.com/seansfkelley).
 * [#133](https://github.com/radar/distance_of_time_in_words/pull/133): Test on Ruby 3.0 and 3.1 - [@dblock](https://github.com/dblock).
 * [#134](https://github.com/radar/distance_of_time_in_words/pull/134): Add support for Dzongkha, the National language of Bhutan - [@KinWang-2013](https://github.com/KinWang-2013).
 * [#135](https://github.com/radar/distance_of_time_in_words/pull/135): Add support for Ruby 2.7 and 3.2, removed support for ruby 2.4, 2.5, 2.6 and Rails 4 - [@KinWang-2013](https://github.com/KinWang-2013).
 * [#136](https://github.com/radar/distance_of_time_in_words/pull/136): Add support for Rails 7 - [@KinWang-2013](https://github.com/KinWang-2013).
-* [#139](https://github.com/radar/distance_of_time_in_words/pull/139): Fix bug with pluralization of Russian translations for numbers ending in 1 - [bitberry-dev](https://github.com/bitberry-dev).
-* Your contribution here.
+* [#139](https://github.com/radar/distance_of_time_in_words/pull/139): Fix bug with pluralization of Russian translations for numbers ending in 1 - [@bitberry-dev](https://github.com/bitberry-dev).
+* [#140](https://github.com/radar/distance_of_time_in_words/pull/140): Add Ruby 3.3 and 3.4 support, added logger - [@dblock](https://github.com/dblock).
+* [#141](https://github.com/radar/distance_of_time_in_words/pull/141): Fix flaky time calculation test by explicitly setting timezone - [@bitberry-dev](https://github.com/bitberry-dev).
+* Fix bug when accumulating on years - [@radar](https://github.com/radar).
 
 ## 5.3.3 (2022/04/25)
 

data/README.markdown

@@ -1,4 +1,4 @@
-# dotiw ![Ruby](https://github.com/radar/distance_of_time_in_words/workflows/Ruby/badge.svg)
+# dotiw ![Ruby](https://github.com/radar/distance_of_time_in_words/workflows/Ruby/badge.svg) [![Coverage Status](https://coveralls.io/repos/github/radar/distance_of_time_in_words/badge.svg?branch=master)](https://coveralls.io/github/radar/distance_of_time_in_words?branch=master)
 
 The `dotiw` library that adds `distance_of_time_in_words` to any Ruby project, or overrides the default implementation in Rails with more accurate output.
 
@@ -32,6 +32,23 @@ include ActionView::Helpers::TextHelper
 include ActionView::Helpers::NumberHelper
 ```
 
+### Rails, without overriding the built-in helpers
+
+Requiring `dotiw` replaces the Rails implementation of `distance_of_time_in_words`
+and `time_ago_in_words`. If you would rather keep the built-in Rails helpers and
+call dotiw explicitly, require `dotiw/core` instead:
+
+```ruby
+gem 'dotiw', require: 'dotiw/core'
+```
+
+This loads `DOTIW::Methods` and the dotiw translations, but leaves
+`ActionView::Helpers::DateHelper` untouched:
+
+```ruby
+DOTIW.distance_of_time_in_words(from_time, to_time, highest_measures: 1)
+```
+
 ## distance\_of\_time\_in\_words
 
 Take this for a totally kick-ass example:
@@ -117,6 +134,8 @@ This will also be passed to `to_sentence`.
 
 Specify this if you want it to use the old `distance_of_time_in_words`. The value can be anything except `nil` or `false`.
 
+Note that `:vague` falls back to Rails/ActionView's own `distance_of_time_in_words`, which looks up its translations under `datetime.distance_in_words`. This namespace is provided by Rails core translations (e.g. via the [rails-i18n](https://github.com/svenfuchs/rails-i18n) gem) for non-English locales, not by dotiw. If you combine `:vague` with a non-English `:locale` and see a "translation missing" error, make sure your application also loads the corresponding Rails translations for that locale (see [#44](https://github.com/radar/distance_of_time_in_words/issues/44)).
+
 #### :include_seconds
 
 As described above this option is the equivalent to the third argument whether to include seconds.
@@ -130,38 +149,67 @@ Specifies the maximum output unit which will accumulate all the surplus. Say you
 => "121 minutes and 10 seconds"
 ```
 
+Note that units below `accumulate_on` are still shown separately. If you want the entire distance expressed as a single number in one unit, use `:max_unit` instead.
+
+#### :max_unit
+
+Expresses the entire distance as a single number in the given unit, discarding (flooring) any remainder smaller than that unit. Unlike `:accumulate_on`, no other units are shown in the output.
+
+```ruby
+>> distance_of_time_in_words(Time.now, Time.now + 1.day, true, max_unit: :seconds)
+=> "86400 seconds"
+
+>> distance_of_time_in_words(Time.now, Time.now + 3.days + 2.hours, true, max_unit: :hours)
+=> "74 hours"
+
+>> distance_of_time_in_words_hash(Time.now, Time.now + 3.days + 2.hours, max_unit: :hours)
+=> {hours: 74}
+```
+
+Valid units are `:seconds`, `:minutes`, `:hours`, `:days`, `:weeks`, `:months` and `:years`.
+
 #### :only
 
 Only want a specific measurement of time? No problem!
 
 ```ruby
 >> distance_of_time_in_words(Time.now, Time.now + 1.hour + 1.minute, false, only: :minutes)
-=> "1 minute"
+=> "61 minutes"
 ```
 
+Excluded measurements are folded into the next smaller included measurement instead of being
+discarded, so the returned duration is always accurate (1 hour + 1 minute = 61 minutes, not 1
+minute).
+
 You only want some? No problem too!
 
 ```ruby
 >> distance_of_time_in_words(Time.now, Time.now + 1.hour + 1.day + 1.minute, false, only: [:minutes, :hours])
-=> "1 hour and 1 minute"
+=> "25 hours and 1 minute"
 ```
 
+Here the excluded day is folded into hours (1 day + 1 hour = 25 hours).
+
 #### :except
 
 Don't want a measurement of time? No problem!
 
 ```ruby
 >> distance_of_time_in_words(Time.now, Time.now + 1.hour + 1.minute, false, except: :minutes)
-=> "1 hour"
+=> "1 hour and 60 seconds"
 ```
 
+The excluded minute is folded into seconds (1 minute = 60 seconds) rather than discarded.
+
 Culling a whole group of measurements of time:
 
 ```ruby
 >> distance_of_time_in_words(Time.now, Time.now + 1.hour + 1.day + 1.minute, false, except: [:minutes, :hours])
-=> "1 day"
+=> "1 day and 3660 seconds"
 ```
 
+The excluded hour and minute cascade down into seconds (1 hour + 1 minute = 3660 seconds).
+
 #### :highest\_measure\_only
 
 > **Deprecated**. Use `highest_measures: 1` instead.

data/RELEASING.md

@@ -0,0 +1,71 @@
+# Releasing DOTIW
+
+There are no hard rules about when to release dotiw. Release bug fixes frequently, features not so frequently and breaking API changes rarely.
+
+## Release
+
+Run tests, check that all tests succeed locally.
+
+```
+bundle install
+rake
+```
+
+Check that the last build succeeded in [GitHub Actions](https://github.com/radar/distance_of_time_in_words/actions) for all supported platforms.
+
+Add a date to this release in [CHANGELOG.md](CHANGELOG.md).
+
+```
+## 5.5.1 (2026/03/28)
+```
+
+Remove the line with "Your contribution here.", since there will be no more contributions to this release.
+
+Commit your changes.
+
+```
+git add CHANGELOG.md lib/dotiw/version.rb
+git commit -m "Preparing for release, 5.5.1."
+git push origin master
+```
+
+Release.
+
+```
+rake release
+```
+
+This builds the gem, creates and pushes a git tag, and pushes the gem to [RubyGems](https://rubygems.org/gems/dotiw).
+
+```
+dotiw 5.5.1 built to pkg/dotiw-5.5.1.gem.
+Tagged v5.5.1.
+Pushed git commits and tags.
+Pushed dotiw 5.5.1 to rubygems.org.
+```
+
+Create a GitHub release for the tag using the `gh` CLI, passing the CHANGELOG entries for this version as the release notes.
+
+```
+gh release create v5.5.1 --title "5.5.1" --notes "$(sed -n '/^## 5.5.1/,/^## /p' CHANGELOG.md | sed '$d')"
+```
+
+## Prepare for the Next Version
+
+Add the next release to [CHANGELOG.md](CHANGELOG.md).
+
+```
+## 5.5.2 (Next)
+
+* Your contribution here.
+```
+
+Increment the patch version number in [lib/dotiw/version.rb](lib/dotiw/version.rb).
+
+Commit your changes.
+
+```
+git add CHANGELOG.md lib/dotiw/version.rb
+git commit -m "Preparing for next developer iteration, 5.5.2."
+git push origin master
+```

data/benchmarks/distance_of_time_in_words_bench.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Benchmark for https://github.com/radar/distance_of_time_in_words/issues/79
+#
+# Compares dotiw's distance_of_time_in_words against Rails' original
+# ActionView::Helpers::DateHelper#distance_of_time_in_words, using the
+# scenario from the issue and its follow-up comments.
+#
+# Run with `ruby benchmarks/distance_of_time_in_words_bench.rb` after
+# `gem install benchmark-ips benchmark-memory actionview`.
+
+require 'active_support'
+require 'active_support/core_ext'
+require 'benchmark/ips'
+require 'benchmark/memory'
+
+require_relative '../lib/dotiw'
+
+begin
+  require 'action_view'
+rescue LoadError
+  warn "This benchmark requires actionview: gem install actionview"
+  exit 1
+end
+
+include ActionView::Helpers::DateHelper
+
+now = Time.now
+future_time = Time.now + 100.years + 30.days + 50.seconds
+
+%i[ips memory].each do |type|
+  Benchmark.public_send(type) do |x|
+    x.report('dotiw') { DOTIW.distance_of_time_in_words(now, future_time) }
+    x.report('rails') { distance_of_time_in_words(now, future_time, include_seconds: true) }
+
+    x.compare!
+  end
+end

data/dotiw.gemspec

@@ -26,10 +26,10 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'pry'
   s.add_development_dependency 'rake'
   s.add_development_dependency 'rspec', '~> 3.0'
-  s.add_development_dependency 'tzinfo', '~> 1.2.7'
   s.add_development_dependency 'mutex_m'
   s.add_development_dependency 'base64'
   s.add_development_dependency 'bigdecimal'
+  s.add_development_dependency 'simplecov'
 
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")

data/gemfiles/rails_8.0.gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# This file was generated by Appraisal
+
+source 'http://rubygems.org'
+
+gem 'rails', '~> 8.0.0'
+gem 'tzinfo', '~> 2.0'
+
+
+gemspec path: '../'

data/gemfiles/rails_8.1.gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# This file was generated by Appraisal
+
+source 'http://rubygems.org'
+
+gem 'rails', '~> 8.1.0'
+gem 'tzinfo', '~> 2.0'
+
+
+gemspec path: '../'

data/gemfiles/rails_8.1_i18n.gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# This file was generated by Appraisal
+
+source 'http://rubygems.org'
+
+gem 'rails', '~> 8.1.0'
+gem 'rails-i18n'
+gem 'tzinfo', '~> 2.0'
+
+gemspec path: '../'

data/lib/dotiw/core.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'i18n'
+require 'logger'
+require 'active_support'
+require 'active_support/core_ext'
+
+module DOTIW
+  extend ActiveSupport::Autoload
+
+  eager_autoload do
+    autoload :VERSION, 'dotiw/version'
+    autoload :TimeHash, 'dotiw/time_hash'
+    autoload :Methods, 'dotiw/methods'
+  end
+
+  extend self
+
+  DEFAULT_I18N_SCOPE = :'datetime.dotiw'
+  DEFAULT_I18N_SCOPE_COMPACT = :'datetime.dotiw_compact'
+
+  # DOTIW.distance_of_time_in_words(...), DOTIW.time_ago_in_words(...), etc.
+  extend Methods
+
+  def init_i18n!
+    I18n.load_path.unshift(*locale_files)
+    I18n.reload!
+  end
+
+  def languages
+    @languages ||= (locale_files.map { |path| path.split(%r{[/.]})[-2].to_sym })
+  end
+
+  def locale_files
+    files 'locale', '*.yml'
+  end
+
+  protected
+
+  def files(directory, ext)
+    Dir[File.join File.dirname(__FILE__), directory, ext]
+  end
+end
+
+DOTIW.init_i18n!

data/lib/dotiw/methods.rb

@@ -102,9 +102,23 @@ module DOTIW
       options[:except] = Array.wrap(options[:except]).map!(&:to_sym) if options[:except]
       options[:only] = Array.wrap(options[:only]).map!(&:to_sym) if options[:only]
 
-      DOTIW::TimeHash::TIME_FRACTIONS.each do |fraction|
-        if options[:except]&.include?(fraction) || (options[:only] && !options[:only].include?(fraction))
-          discarded_hash[fraction] = hash.delete fraction
+      if options[:except] || options[:only]
+        # Fold excluded fractions into the next smaller fraction instead of discarding their
+        # duration outright, e.g. weeks excluded via only: [:years, :months, :days] are converted
+        # to days and added to the days count, rather than losing those weeks entirely. Larger
+        # fractions are processed first so that a run of consecutive excluded fractions cascades
+        # down to the largest fraction that's still included (or is dropped if none remain).
+        DOTIW::TimeHash::TIME_FRACTIONS.reverse_each do |fraction|
+          next unless hash.key?(fraction)
+          next unless options[:except]&.include?(fraction) || (options[:only] && !options[:only].include?(fraction))
+
+          value = hash.delete(fraction)
+          discarded_hash[fraction] = value
+
+          next_fraction = _next_smaller_fraction(fraction)
+          next unless next_fraction
+
+          hash[next_fraction] = hash.fetch(next_fraction, 0) + (value * ROLLUP_THRESHOLDS[next_fraction])
         end
       end
 
@@ -117,12 +131,13 @@ module DOTIW
         fractions &= options[:only] if options[:only]
         fractions -= options[:except] if options[:except]
 
-        I18n.with_options locale: options[:locale], scope: i18n_scope do |locale|
-          # e.g. try to format 'less than 1 days', fallback to '0 days'
-          return locale.translate :less_than_x,
-                                  distance: locale.translate(fractions.first, count: 1),
-                                  default: locale.translate(fractions.first, count: 0)
-        end
+        locale = options[:locale]
+        # e.g. try to format 'less than 1 days', fallback to '0 days'
+        return I18n.translate :less_than_x,
+                              locale: locale,
+                              scope: i18n_scope,
+                              distance: I18n.translate(fractions.first, locale: locale, scope: i18n_scope, count: 1),
+                              default: I18n.translate(fractions.first, locale: locale, scope: i18n_scope, count: 0)
       end
 
       options.delete(:except)
@@ -137,10 +152,8 @@ module DOTIW
         _maybe_round! hash, discarded_hash, highest_measures[:remainder]
       end
 
-      phrases = []
-      I18n.with_options locale: options[:locale], scope: i18n_scope do |locale|
-        phrases = hash.map { |key, value| locale.t(key, count: value) }
-      end
+      locale = options[:locale]
+      phrases = hash.map { |key, value| I18n.translate(key, locale: locale, scope: i18n_scope, count: value) }
 
       options[:words_connector] ||= I18n.translate :"#{i18n_scope}.words_connector",
                                                    default: :'support.array.words_connector',
@@ -152,7 +165,7 @@ module DOTIW
                                                        default: :'support.array.last_word_connector',
                                                        locale: options[:locale]
 
-      phrases.to_sentence(options.except(:accumulate_on, :compact))
+      phrases.to_sentence(options.except(:accumulate_on, :max_unit, :compact))
     end
 
     def _compute_highest_measures!(options)
@@ -192,6 +205,13 @@ module DOTIW
       end
     end
 
+    def _next_smaller_fraction(fraction)
+      index = DOTIW::TimeHash::TIME_FRACTIONS.index(fraction)
+      return nil if index.nil? || index.zero?
+
+      DOTIW::TimeHash::TIME_FRACTIONS[index - 1]
+    end
+
     def _rollup!(hash, smallest_measure_index)
       DOTIW::TimeHash::TIME_FRACTIONS[smallest_measure_index..-1].each_with_index do |fraction, index|
         if hash.fetch(fraction, 0) >= ROLLUP_THRESHOLDS[fraction]

data/lib/dotiw/time_hash.rb

@@ -13,15 +13,9 @@ module DOTIW
       @from_time  = from_time || Time.current
       @to_time    = to_time   || (@to_time_not_given = true && @from_time + distance.seconds)
       @smallest, @largest = [@from_time, @to_time].minmax
-      @to_time   += 1.hour if @to_time_not_given && smallest.dst? && !largest.dst?
-      @to_time   -= 1.hour if @to_time_not_given && !smallest.dst? && largest.dst?
+      @to_time += offset_delta(smallest, largest) if @to_time_not_given
       @smallest, @largest = [@from_time, @to_time].minmax
-      @distance ||= begin
-        d = largest - smallest
-        d -= 1.hour if smallest.dst? && !largest.dst?
-        d += 1.hour if !smallest.dst? && largest.dst?
-        d
-      end
+      @distance ||= (largest - smallest) + offset_delta(smallest, largest)
 
       build_time_hash
     end
@@ -40,8 +34,22 @@ module DOTIW
     ONE_WEEK = 7.days.freeze
     FOUR_WEEKS = 28.days.freeze
 
+    # The distance between two Time objects computed via subtraction already
+    # 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.
+    def offset_delta(smallest, largest)
+      largest.utc_offset - smallest.utc_offset
+    end
+
     def build_time_hash
-      if accumulate_on = options[:accumulate_on]
+      if (max_unit = options[:max_unit])
+        build_max_unit(max_unit.to_sym)
+      elsif accumulate_on = options[:accumulate_on]
         accumulate_on = accumulate_on.to_sym
         TIME_FRACTIONS.index(accumulate_on).downto(0) { |i| send("build_#{TIME_FRACTIONS[i]}") }
       else
@@ -86,6 +94,44 @@ module DOTIW
       output[:weeks], @distance = distance.divmod(ONE_WEEK.to_i) unless output[:weeks]
     end
 
+    # Expresses the entire distance as a single number in the given unit, discarding
+    # (flooring) any remainder smaller than that unit, unlike +accumulate_on+ which keeps
+    # showing the smaller units below the target.
+    def build_max_unit(unit)
+      case unit
+      when :seconds
+        output[:seconds] = distance.to_i
+      when :minutes
+        output[:minutes] = (distance / ONE_MINUTE).floor
+      when :hours
+        output[:hours] = (distance / ONE_HOUR).floor
+      when :days
+        output[:days] = (distance / ONE_DAY).floor
+      when :weeks
+        output[:weeks] = (distance / ONE_WEEK).floor
+      when :months
+        output[:months] = whole_months_between(smallest, largest)
+      when :years
+        output[:years] = whole_years_between(smallest, largest)
+      else
+        raise ArgumentError, "unrecognized max_unit #{unit.inspect}"
+      end
+
+      @distance = 0
+    end
+
+    def whole_months_between(from, to)
+      months = (to.year - from.year) * 12 + (to.month - from.month)
+      months -= 1 if to.advance(months: -months) < from
+      months
+    end
+
+    def whole_years_between(from, to)
+      years = to.year - from.year
+      years -= 1 if to.advance(years: -years) < from
+      years
+    end
+
     def build_months
       build_years_months_weeks_days
 

data/lib/dotiw/version.rb

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

data/lib/dotiw.rb

@@ -1,45 +1,6 @@
 # frozen_string_literal: true
 
-require 'i18n'
-require 'logger'
-require 'active_support'
-require 'active_support/core_ext'
-
-module DOTIW
-  extend ActiveSupport::Autoload
-
-  eager_autoload do
-    autoload :VERSION, 'dotiw/version'
-    autoload :TimeHash, 'dotiw/time_hash'
-    autoload :Methods, 'dotiw/methods'
-  end
-
-  extend self
-
-  DEFAULT_I18N_SCOPE = :'datetime.dotiw'
-  DEFAULT_I18N_SCOPE_COMPACT = :'datetime.dotiw_compact'
-
-  def init_i18n!
-    I18n.load_path.unshift(*locale_files)
-    I18n.reload!
-  end
-
-  def languages
-    @languages ||= (locale_files.map { |path| path.split(%r{[/.]})[-2].to_sym })
-  end
-
-  def locale_files
-    files 'dotiw/locale', '*.yml'
-  end
-
-  protected
-
-  def files(directory, ext)
-    Dir[File.join File.dirname(__FILE__), directory, ext]
-  end
-end
-
-DOTIW.init_i18n!
+require_relative 'dotiw/core'
 
 begin
   require 'action_view'

data/spec/lib/dotiw_module_spec.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe DOTIW do
+  START_TIME_MODULE = '01-08-2009'.to_time(:utc)
+
+  before do
+    I18n.locale = :en
+  end
+
+  describe '.distance_of_time_in_words' do
+    it 'returns the exact distance' do
+      expect(
+        described_class.distance_of_time_in_words(START_TIME_MODULE, START_TIME_MODULE + 1.hour + 30.minutes)
+      ).to eq('1 hour and 30 minutes')
+    end
+
+    it 'accepts options' do
+      expect(
+        described_class.distance_of_time_in_words(
+          START_TIME_MODULE, START_TIME_MODULE + 1.hour + 30.minutes, highest_measures: 1
+        )
+      ).to eq('1 hour')
+    end
+  end
+
+  describe '.time_ago_in_words' do
+    it 'returns the distance to now' do
+      allow(Time).to receive(:now).and_return(START_TIME_MODULE)
+      allow(Time.zone).to receive(:now).and_return(START_TIME_MODULE)
+
+      expect(
+        described_class.time_ago_in_words(START_TIME_MODULE - 90, include_seconds: true)
+      ).to eq('1 minute and 30 seconds')
+    end
+  end
+
+  describe '.distance_of_time' do
+    it 'returns the distance for a number of seconds' do
+      expect(described_class.distance_of_time(90)).to eq('1 minute and 30 seconds')
+    end
+  end
+
+  describe '.distance_of_time_in_words_hash' do
+    it 'returns the distance as a hash' do
+      expect(
+        described_class.distance_of_time_in_words_hash(START_TIME_MODULE, START_TIME_MODULE + 1.hour + 30.minutes)
+      ).to include(hours: 1, minutes: 30)
+    end
+  end
+end

data/spec/lib/dotiw_spec.rb

@@ -17,7 +17,11 @@ describe 'A better distance_of_time_in_words' do
 
   before do
     I18n.locale = :en
-    ActiveSupport.to_time_preserves_timezone = :zone
+    # This config is deprecated as of Rails 8.1 (it becomes the permanent,
+    # non-configurable behavior) and is removed entirely in Rails 8.2.
+    if Gem::Version.new(ActiveSupport::VERSION::STRING) < Gem::Version.new('8.1')
+      ActiveSupport.to_time_preserves_timezone = :zone
+    end
 
     allow(Time).to receive(:now).and_return(START_TIME)
     allow(Time.zone).to receive(:now).and_return(START_TIME)
@@ -193,6 +197,63 @@ describe 'A better distance_of_time_in_words' do
       end
     end
 
+    context 'in timezones with an inverted DST scheme (#63)' do
+      # Real, non-mocked reproduction from #63: running the suite under
+      # certain timezones (e.g. Europe/Dublin, where IST is "standard" time
+      # and GMT is technically the DST offset) previously failed because
+      # Time#dst? disagreed between a Time built via Time.at(datetime) and
+      # one built via datetime.to_time for the exact same instant, even
+      # though their utc_offset was identical. This caused a spurious +/-1
+      # hour "DST correction" to be applied.
+      around do |example|
+        original_tz = ENV.fetch('TZ', nil)
+        ENV['TZ'] = tz
+        example.run
+        ENV['TZ'] = original_tz
+      end
+
+      %w[
+        Europe/Dublin
+        Africa/Casablanca
+        Asia/Tehran
+        Europe/Moscow
+        Asia/Gaza
+      ].each do |timezone|
+        context "TZ=#{timezone}" do
+          let(:tz) { timezone }
+
+          it 'is 1 minute' do
+            start = Time.at(DateTime.now)
+            finish = DateTime.now + 1.minute
+
+            expect(distance_of_time_in_words(start, finish)).to eq('1 minute')
+          end
+        end
+      end
+    end
+
+    context 'across a historical UTC offset change (#153)' do
+      # Real, non-mocked reproduction from #153: Pacific/Norfolk permanently
+      # changed its UTC offset from +11:30 to +11:00 on 2015-10-04 (a
+      # tzdata rule change, not a recurring DST transition - both endpoints
+      # report dst? == false). The calendar distance (years/months/weeks/
+      # days) was correct, but the leftover hours/minutes leaked the 30
+      # minute offset difference as a spurious "23 hours and 30 minutes".
+      around do |example|
+        original_tz = ENV.fetch('TZ', nil)
+        ENV['TZ'] = 'Pacific/Norfolk'
+        example.run
+        ENV['TZ'] = original_tz
+      end
+
+      it 'is 1 year and 2 months, not 1 year, 2 months, 23 hours, and 30 minutes' do
+        start = '2015-1-15'.to_time
+        finish = '2016-3-15'.to_time
+
+        expect(distance_of_time_in_words(start, finish, true)).to eq('1 year and 2 months')
+      end
+    end
+
     describe 'accumulate_on:' do
       [
         [START_TIME,
@@ -228,6 +289,55 @@ describe 'A better distance_of_time_in_words' do
       end
     end
 
+    describe 'max_unit:' do
+      [
+        [START_TIME,
+         START_TIME + 10.minute,
+         :seconds,
+         { seconds: 600 },
+         '600 seconds'],
+        [START_TIME,
+         START_TIME + 10.hour + 10.minute + 1.second,
+         :minutes,
+         { minutes: 610 },
+         '610 minutes'],
+        [START_TIME,
+         START_TIME + 2.day + 10_000.hour + 10.second,
+         :hours,
+         { hours: 10_048 },
+         '10048 hours'],
+        [START_TIME,
+         START_TIME + 2.day + 10_000.hour + 10.second,
+         :days,
+         { days: 418 },
+         '418 days'],
+        [START_TIME,
+         START_TIME + 2.day + 10_000.hour + 10.second,
+         :weeks,
+         { weeks: 59 },
+         '59 weeks'],
+        ['2015-1-15'.to_time, '2016-3-15'.to_time, :months, { months: 14 }, '14 months'],
+        ['2015-1-15'.to_time, '2016-3-15'.to_time, :years, { years: 1 }, '1 year']
+      ].each do |start, finish, unit, hash, output|
+        it "should be #{output}" do
+          expect(distance_of_time_in_words_hash(start, finish, max_unit: unit)).to eq(hash)
+          expect(distance_of_time_in_words(start, finish, true, max_unit: unit)).to eq(output)
+        end
+      end
+
+      it 'floors and discards any remainder smaller than the unit' do
+        expect(
+          distance_of_time_in_words_hash(START_TIME, START_TIME + 1.year - 1.day, max_unit: :years)
+        ).to eq(years: 0)
+      end
+
+      it 'raises for an unrecognized unit' do
+        expect do
+          distance_of_time_in_words_hash(START_TIME, START_TIME + 1.day, max_unit: :fortnights)
+        end.to raise_error(ArgumentError, /unrecognized max_unit/)
+      end
+    end
+
     describe 'without finish time' do
       # A missing finish argument should default to zero, essentially returning
       # the equivalent of distance_of_time in order to be backwards-compatible
@@ -297,22 +407,28 @@ describe 'A better distance_of_time_in_words' do
       [START_TIME,
        START_TIME + 1.year + 2.months + 3.days + 4.hours + 5.minutes + 6.seconds,
        { except: 'minutes' },
-       '1 year, 2 months, 3 days, 4 hours, and 6 seconds'],
+       # 5 excluded minutes are folded into seconds (5 * 60 + 6 = 306) instead of being discarded.
+       '1 year, 2 months, 3 days, 4 hours, and 306 seconds'],
       [START_TIME,
        START_TIME + 1.hour + 1.minute,
-       { except: 'minutes' }, '1 hour'],
+       { except: 'minutes' },
+       # The excluded minute is folded into seconds (1 * 60 = 60) instead of being discarded.
+       '1 hour and 60 seconds'],
       [START_TIME,
        START_TIME + 1.hour + 1.day + 1.minute,
        { except: %w[minutes hours] },
-       '1 day'],
+       # The excluded hour and minute cascade down into seconds (1 * 24 * 60 * 60 + 1 * 60 = 3660).
+       '1 day and 3660 seconds'],
       [START_TIME,
        START_TIME + 1.hour + 1.day + 1.minute,
        { only: %w[minutes hours] },
-       '1 hour and 1 minute'],
+       # The excluded day is folded into hours (1 * 24 + 1 = 25) instead of being discarded.
+       '25 hours and 1 minute'],
       [START_TIME,
        START_TIME + 1.year + 2.months + 3.weeks + 4.days + 5.hours + 6.minutes + 7.seconds,
        { except: 'minutes' },
-       '1 year, 2 months, 3 weeks, 4 days, 5 hours, and 7 seconds'],
+       # 6 excluded minutes are folded into seconds (6 * 60 + 7 = 367) instead of being discarded.
+       '1 year, 2 months, 3 weeks, 4 days, 5 hours, and 367 seconds'],
       [START_TIME,
        START_TIME + 1.hour + 2.minutes + 3.seconds,
        { highest_measure_only: true },
@@ -395,6 +511,34 @@ describe 'A better distance_of_time_in_words' do
       end.to raise_error(ArgumentError)
     end
 
+    describe 'folding excluded fractions into included ones (regression for #77 and #120)' do
+      it 'folds excluded weeks into days rather than discarding them' do
+        from = '2019-01-02'.to_time
+        to = '2020-12-28'.to_time
+        expect(distance_of_time_in_words(from, to, false, only: %i[years months days]))
+          .to eq('1 year, 11 months, and 26 days')
+      end
+
+      it 'folds excluded weeks into days when using except' do
+        from = '2019-01-02'.to_time
+        to = '2020-12-28'.to_time
+        expect(distance_of_time_in_words(from, to, false, except: :weeks))
+          .to eq('1 year, 11 months, and 26 days')
+      end
+
+      it 'folds an excluded month into days' do
+        expect(distance_of_time_in_words(START_TIME, START_TIME + 1.month + 9.days, false, only: %i[months days]))
+          .to eq('1 month and 9 days')
+      end
+
+      it 'converts a negative day count into a week when the day-of-month matches but the hour rolls back' do
+        from = Time.new(2024, 5, 1, 10, 0, 0)
+        to = Time.new(2024, 6, 1, 9, 0, 0)
+        expect(distance_of_time_in_words(from, to, false, only: %i[months weeks days]))
+          .to eq('4 weeks and 2 days')
+      end
+    end
+
     if defined?(ActionView)
       describe 'ActionView without include seconds argument' do
         [
@@ -440,13 +584,31 @@ describe 'A better distance_of_time_in_words' do
           [START_TIME,
            START_TIME + 1.year + 2.months + 3.weeks + 4.days + 5.hours + 6.minutes + 7.seconds,
            { vague: nil },
-           '1 year, 2 months, 3 weeks, 4 days, 5 hours, 6 minutes, and 7 seconds']
+           '1 year, 2 months, 3 weeks, 4 days, 5 hours, 6 minutes, and 7 seconds'],
+          [START_TIME,
+           START_TIME + 1.year + 2.months,
+           { vague: true, locale: :en },
+           'about 1 year']
         ].each do |start, finish, options, output|
           it "should be #{output}" do
             expect(distance_of_time_in_words(start, finish, true, options)).to eq(output)
           end
         end
 
+        # requires the rails-i18n gem for non-English datetime.distance_in_words translations, see #44
+        if defined?(RailsI18n)
+          it 'should be rundt 1 år for vague: true, locale: :nb' do
+            finish = START_TIME + 1.year + 2.months
+            expect(distance_of_time_in_words(START_TIME, finish, true, vague: true, locale: :nb)).to eq('rundt 1 år')
+          end
+        else
+          it 'returns a translation missing message for vague: true, locale: :nb without the rails-i18n gem' do
+            finish = START_TIME + 1.year + 2.months
+            expect(distance_of_time_in_words(START_TIME, finish, true, vague: true, locale: :nb))
+              .to eq('Translation missing: nb.datetime.distance_in_words.about_x_years')
+          end
+        end
+
         context 'via ActionController::Base.helpers' do
           it '#distance_of_time_in_words' do
             end_time = START_TIME + 1.year + 2.months + 3.weeks + 4.days + 5.hours + 6.minutes + 7.seconds

data/spec/spec_helper.rb

@@ -3,8 +3,27 @@
 ROOT_PATH = File.join(File.dirname(__FILE__), '..')
 $LOAD_PATH.unshift ROOT_PATH unless $LOAD_PATH.include? ROOT_PATH
 
+require 'simplecov'
+SimpleCov.start do
+  add_filter '/spec/'
+end
+
+# Ruby 3.4 dropped concurrent-ruby's implicit require of logger, which older
+# Rails versions rely on being already loaded, see https://github.com/rails/rails/issues/54271.
+require 'logger'
+require 'bundler'
+Bundler.require
+
 require 'dotiw'
 
+# Loads Rails' own datetime.distance_in_words translations for non-English
+# locales, needed by the vague: true option, which falls back to Rails'
+# native distance_of_time_in_words instead of dotiw's own translations, see #44.
+# Only present when the rails-i18n gem is in the Gemfile (see gemfiles/rails_8.1_i18n.gemfile).
+if defined?(RailsI18n)
+  I18n.load_path += Dir[File.join(Gem.loaded_specs['rails-i18n'].gem_dir, 'rails', 'locale', '*.yml')]
+end
+
 Time.zone = 'UTC'
 
 I18n.locale = :en

metadata

@@ -1,14 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: dotiw
 version: !ruby/object:Gem::Version
-  version: 5.5.0
+  version: 5.6.0
 platform: ruby
 authors:
 - Ryan Bigg
 - Lauran Jansen
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-08-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -109,21 +110,21 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.0'
 - !ruby/object:Gem::Dependency
-  name: tzinfo
+  name: mutex_m
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 1.2.7
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 1.2.7
+        version: '0'
 - !ruby/object:Gem::Dependency
-  name: mutex_m
+  name: base64
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -137,7 +138,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: base64
+  name: bigdecimal
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -151,7 +152,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: bigdecimal
+  name: simplecov
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -187,7 +188,9 @@ files:
 - Gemfile
 - MIT-LICENSE
 - README.markdown
+- RELEASING.md
 - Rakefile
+- benchmarks/distance_of_time_in_words_bench.rb
 - benchmarks/time_hash_bench.rb
 - dotiw.gemspec
 - gemfiles/.bundle/config
@@ -198,8 +201,12 @@ files:
 - gemfiles/rails_7.0.gemfile
 - gemfiles/rails_7.1.gemfile
 - gemfiles/rails_7.2.gemfile
+- gemfiles/rails_8.0.gemfile
+- gemfiles/rails_8.1.gemfile
+- gemfiles/rails_8.1_i18n.gemfile
 - lib/dotiw.rb
 - lib/dotiw/action_view/helpers/date_helper.rb
+- lib/dotiw/core.rb
 - lib/dotiw/locale/ar.yml
 - lib/dotiw/locale/da.yml
 - lib/dotiw/locale/de.yml
@@ -223,6 +230,7 @@ files:
 - lib/dotiw/methods.rb
 - lib/dotiw/time_hash.rb
 - lib/dotiw/version.rb
+- spec/lib/dotiw_module_spec.rb
 - spec/lib/dotiw_spec.rb
 - spec/lib/i18n/ar.yml
 - spec/lib/i18n/da.yml
@@ -249,6 +257,7 @@ homepage: https://github.com/radar/distance_of_time_in_words
 licenses:
 - MIT
 metadata: {}
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -263,10 +272,12 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.5.16
+signing_key:
 specification_version: 4
 summary: Better distance_of_time_in_words for Rails
 test_files:
+- spec/lib/dotiw_module_spec.rb
 - spec/lib/dotiw_spec.rb
 - spec/lib/i18n/ar.yml
 - spec/lib/i18n/da.yml