periodoxical 2.2.1 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a17e3bd272fdd537b16689e871aa834c6388202d36d5ed5bf420150c0ff62bd
-  data.tar.gz: 8c08b584338f8d2e14cb8c0c8ce1ec4171d5fa4c946328911b25302aa621e92e
+  metadata.gz: 169a25ff421b59755693ae84a7b909dde7346c3c3d05a7ebef0e363227ba247d
+  data.tar.gz: a4ff2b417b4be13c3c98ee4c9843aab54d7f346447a486084dcba32e20ea388a
 SHA512:
-  metadata.gz: 76df9351805289b310b079dd0a44587630db263101a18777ffa4612dacd5e846313fc56b8836ffa42fe7126926456d11273c218187dda0542d5b76c65a6a0451
-  data.tar.gz: afed95be8919055c47c5b118b6e01f944b03e16fc2c87046157ece131d35d0078c1dc5cbad804140afb9cdc975283c9d464536a4b65d7549181b5e0781afb628
+  metadata.gz: cd1a0ed4ba0f34ccf10fede5d036bddf317e801abdd8734931c3f2cdad707d7057ef6eee25410bf8e3af8c46c1299e982fa029bbc10a48acbc6e5360ab8ead68
+  data.tar.gz: 0d6c4234da26fe9c67653b32c69978e9703390bd10d6571703c6f56b5db2f5b2684f3ebd9543a37b94716d18c78e24584616f89ffd2b019c244a99bd0a917326

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    periodoxical (2.2.1)
+    periodoxical (2.3.0)
       tzinfo (~> 2.0, >= 2.0.0)
 
 GEM

data/README.md

@@ -562,6 +562,39 @@ Periodoxical.generate(
 ]
 ```
 
+### Daylight Saving Time (DST) handling
+
+Periodoxical supports explicit strategies for DST edge cases when converting local times to UTC:
+
+- ambiguous_time: how to resolve fall-back ambiguous local times (e.g., 01:30 occurs twice)
+  - :first → choose the first occurrence (usually daylight time)
+  - :last → choose the second occurrence (standard time)
+  - :raise → raise TZInfo::AmbiguousTime (default)
+- gap_strategy: how to handle spring-forward missing local times (e.g., 02:30 does not exist)
+  - :advance → move forward by gap_shift_minutes to the next valid local time
+  - :skip → drop the invalid block
+  - :raise → raise TZInfo::PeriodNotFound (default)
+- gap_shift_minutes: integer minutes to advance when gap_strategy is :advance (default: 60)
+
+Example: be resilient around DST changes
+
+```rb
+Periodoxical.generate(
+  time_zone: 'America/Los_Angeles',
+  ambiguous_time: :last,      # pick standard time on fall back
+  gap_strategy: :advance,     # move to next valid time on spring forward
+  gap_shift_minutes: 60,
+  starting_from: '2025-03-01',
+  ending_at:   '2025-11-30',
+  time_blocks: [ { start_time: '1:30AM', end_time: '2:30AM' } ]
+)
+```
+
+Notes:
+- Period offsets are applied based on the period at that instant, not the current period.
+- If you choose `gap_strategy: :skip`, blocks that convert to invalid local times will be omitted.
+
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/periodoxical/version.rb

@@ -1,3 +1,3 @@
 module Periodoxical
-  VERSION = "2.2.1"
+  VERSION = "2.3.0"
 end

data/lib/periodoxical.rb

@@ -71,6 +71,14 @@ module Periodoxical
     #     - 9:00AM - 9:20AM
     #     - 9:20AM - 9:40AM
     #     - 9:40AM - 10:00AM
+    # @param [Symbol] ambiguous_time
+    #   How to resolve DST fall-back ambiguous local times (e.g. 01:30 occurs twice).
+    #   Allowed: :first (daylight time), :last (standard time), :raise (default).
+    # @param [Symbol] gap_strategy
+    #   How to handle DST spring-forward missing local times (e.g. 02:30 does not exist).
+    #   Allowed: :advance (shift forward), :skip (omit block), :raise (default).
+    # @param [Integer] gap_shift_minutes
+    #   Minutes to advance when gap_strategy is :advance. Default: 60.
     def initialize(
       starting_from:,
       ending_at: nil,
@@ -84,10 +92,16 @@ module Periodoxical
       nth_day_of_week_in_month: nil,
       days_of_month: nil,
       duration: nil,
-      months: nil
+      months: nil,
+      ambiguous_time: :raise,
+      gap_strategy: :raise,
+      gap_shift_minutes: 60
     )
 
       @time_zone = TZInfo::Timezone.get(time_zone)
+      @ambiguous_time = ambiguous_time
+      @gap_strategy = gap_strategy
+      @gap_shift_minutes = gap_shift_minutes
       if days_of_week.is_a?(Array)
         @days_of_week = deep_symbolize_keys(days_of_week)
       elsif days_of_week.is_a?(Hash)
@@ -144,9 +158,16 @@ module Periodoxical
 
     private
 
+    # @param [Date] date
     # @param [String] time_str
     #   Ex: '9:00AM'
-    # @param [Date] date
+    #
+    # @return [DateTime]
+    # Converts a local date and time string to UTC and returns a DateTime with the
+    # timezone offset corresponding to the zone period at that instant.
+    # Handles DST transitions explicitly:
+    #  - Ambiguous (fall-back) times resolved via `@ambiguous_time`.
+    #  - Missing (spring-forward) times handled via `@gap_strategy` and `@gap_shift_minutes`.
     def time_str_to_object(date, time_str)
       time = Time.strptime(time_str, '%I:%M%p')
       date_time = DateTime.new(
@@ -157,7 +178,51 @@ module Periodoxical
         time.min,
         time.sec,
       )
-      @time_zone.local_to_utc(date_time).new_offset(@time_zone.current_period.offset.utc_total_offset)
+      utc_time = begin
+        @time_zone.local_to_utc(date_time) do |periods|
+          case @ambiguous_time
+          when :first
+            periods.first
+          when :last
+            periods.last
+          when :raise
+            raise TZInfo::AmbiguousTime, date_time.to_s
+          else
+            periods.last
+          end
+        end
+      rescue TZInfo::AmbiguousTime
+        case @ambiguous_time
+        when :first
+          @time_zone.local_to_utc(date_time) { |periods| periods.first }
+        when :last
+          @time_zone.local_to_utc(date_time) { |periods| periods.last }
+        else
+          raise
+        end
+      rescue TZInfo::PeriodNotFound
+        case @gap_strategy
+        when :advance
+          step = Rational(@gap_shift_minutes, 24 * 60)
+          shifted = date_time
+          attempts = 0
+          begin
+            shifted += step
+            attempts += 1
+            raise TZInfo::PeriodNotFound if attempts > 240
+            @time_zone.local_to_utc(shifted)
+          rescue TZInfo::PeriodNotFound
+            retry
+          end
+        when :skip
+          return nil
+        else
+          raise
+        end
+      end
+
+      period_at_utc = @time_zone.period_for_utc(utc_time)
+      utc_time.new_offset(period_at_utc.offset.utc_total_offset)
     end
 
     # @param [Date] date
@@ -212,6 +277,8 @@ module Periodoxical
       strtm = time_str_to_object(@current_date, time_block[:start_time])
       endtm = time_str_to_object(@current_date, time_block[:end_time])
 
+      return if strtm.nil? || endtm.nil?
+
       if @duration
         split_by_duration_and_append(strtm, endtm)
       else
@@ -395,6 +462,7 @@ module Periodoxical
 
       if @starting_from.is_a?(DateTime)
         start_time = time_str_to_object(@current_date, time_block[:start_time])
+        return false if start_time.nil?
 
         # If the candidate time block is starting earlier than @starting_from, we want to skip it
         return true if start_time < @starting_from
@@ -402,6 +470,7 @@ module Periodoxical
 
       if @ending_at.is_a?(DateTime)
         end_time = time_str_to_object(@current_date, time_block[:end_time])
+        return false if end_time.nil?
 
         # If the candidate time block is ending after @ending_at, we want to skip it
         return true if end_time > @ending_at

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: periodoxical
 version: !ruby/object:Gem::Version
-  version: 2.2.1
+  version: 2.3.0
 platform: ruby
 authors:
 - Steven Li
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-07-06 00:00:00.000000000 Z
+date: 2025-08-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tzinfo