periodoxical 2.2.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ace9209a6c531a382b264e87513dc6e5075499fc90f1eba313404368d96e58ba
-  data.tar.gz: e1771a96128f204df520f39bfcb54d3a294c130da07d0c9f971b98908fe985ce
+  metadata.gz: 169a25ff421b59755693ae84a7b909dde7346c3c3d05a7ebef0e363227ba247d
+  data.tar.gz: a4ff2b417b4be13c3c98ee4c9843aab54d7f346447a486084dcba32e20ea388a
 SHA512:
-  metadata.gz: aaaf84f0c0af53ad1df2f595298a8327fc67574b7a35c08a27a921f0719ef6eea0990a7ee28423755f3baa0abe78d31e4bad7bcd42f82d1c9ebe6607b0fe0574
-  data.tar.gz: 8eed0bfd9236bb43084c0427a50ac6ce6b793411d30adffd1d12b303ae57d0cf8d5dc0281b1c654aa15584a436066dea7f1a39a5283bdc7ef398df9dde56ec5c
+  metadata.gz: cd1a0ed4ba0f34ccf10fede5d036bddf317e801abdd8734931c3f2cdad707d7057ef6eee25410bf8e3af8c46c1299e982fa029bbc10a48acbc6e5360ab8ead68
+  data.tar.gz: 0d6c4234da26fe9c67653b32c69978e9703390bd10d6571703c6f56b5db2f5b2684f3ebd9543a37b94716d18c78e24584616f89ffd2b019c244a99bd0a917326

data/Gemfile.lock

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

data/README.md

@@ -240,7 +240,8 @@ Periodoxical.generate(
 ]
 ```
 
-### Example 6 - Specify nth day-of-week in month (ie. first Monday of the Month, second Tuesday of the Month, last Friday of Month)
+### Specify nth day-of-week in month (ie. first Monday of the Month, second Tuesday of the Month, last Friday of Month)
+
 As a Ruby dev, I want to generate timeblocks for **8AM - 9AM** on the **first and second Mondays**  and **last Fridays** of every month starting in June 2024.  I can do this with the `nth_day_of_week_in_month` param.
 
 ```rb
@@ -281,7 +282,7 @@ Periodoxical.generate(
 ]
 ```
 
-### Example 7 - Exclude time blocks using the `exclusion_dates` and `exclusion_times` parameters
+### Exclude time blocks using the `exclusion_dates` and `exclusion_times` parameters
 As a Ruby dev, I want to generate timeblocks for **8AM - 9AM** on **Mondays**, except for the **Monday of June 10, 2024**.  I can do this using the `exlcusion_dates` parameter.
 
 ```rb
@@ -367,7 +368,7 @@ Periodoxical.generate(
 ]
 ```
 
-### Example 8 - Every-other-nth day-of-week rules (ie. every other Tuesday, every 3rd Wednesday, every 10th Friday)
+### Every-other-nth day-of-week rules (ie. every other Tuesday, every 3rd Wednesday, every 10th Friday)
 
 As a Ruby dev, I want to generate timeblocks for **9AM- 10AM** on **every Monday**, but **every other Tuesday**, and **every other 3rd Wednesday**. I can do this using the `days_of_week` parameter with the `every` and `every_other_nth` keys to specify the every-other-nth-rules.
 
@@ -561,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/helpers.rb

@@ -27,11 +27,14 @@ module Periodoxical
       tb_2_start = time_block_2[:start]
       tb_2_end = time_block_2[:end]
 
-      # Basicall overlap is when one starts before the other has ended
+      # Basically overlap is when one starts before the other has ended
       return true if tb_1_end > tb_2_start && tb_1_end < tb_2_end
       # By symmetry
       return true if tb_2_end > tb_1_start && tb_2_end < tb_1_end
 
+      # Handle the edge case where they start/end at the same time
+      return true if tb_1_start == tb_2_start || tb_1_end == tb_2_end
+
       false
     end
 

data/lib/periodoxical/version.rb

@@ -1,3 +1,3 @@
 module Periodoxical
-  VERSION = "2.2.0"
+  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,11 +158,18 @@ 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")
+      time = Time.strptime(time_str, '%I:%M%p')
       date_time = DateTime.new(
         date.year,
         date.month,
@@ -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
@@ -209,19 +274,21 @@ module Periodoxical
     #  }
     #  Generates time block but also checks if we should stop generating
     def append_to_output_and_check_limit(time_block)
-      # Check if this particular time is conflicts with any times from `exclusion_times`.
-      return if overlaps_with_an_excluded_time?(time_block)
-      return if before_starting_from_or_after_ending_at?(time_block)
-
       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
+        # Check if this particular time is conflicts with any times from `exclusion_times`.
+        return if before_starting_from_or_after_ending_at?(time_block)
+        return if overlaps_with_an_excluded_time?({ start: strtm, end: endtm })
+
         @output << {
           start: strtm,
-          end: endtm 
+          end: endtm
         }
         increment_and_check_limit
       end
@@ -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
@@ -410,19 +479,22 @@ module Periodoxical
       false
     end
 
+    # @param [Hash] time_block
+    # Ex:
+    #   {
+    #     start: #<DateTime>,
+    #     end: #<DateTime>,
+    #   }
     # @return [Boolean]
     #   Whether or not the given `time_block` in the @current_date and
     #   @time_zone overlaps with the times in `exclusion_times`.
-    def overlaps_with_an_excluded_time?(time_block)
+    def overlaps_with_an_excluded_time?(tm_blck)
       return false unless @exclusion_times
 
       @exclusion_times.each do |exclusion_timeblock|
         return true if overlap?(
           exclusion_timeblock,
-          {
-            start: time_str_to_object(@current_date, time_block[:start_time]),
-            end: time_str_to_object(@current_date, time_block[:end_time]),
-          }
+          tm_blck
         )
       end
 
@@ -434,13 +506,15 @@ module Periodoxical
       si = strtm
       ei = strtm + delta
       while ei <= endtm
-        @output << {
-          start: si,
-          end: ei
-        }
+        unless overlaps_with_an_excluded_time?({ start: si, end: ei })
+          @output << {
+            start: si,
+            end: ei
+          }
+          increment_and_check_limit
+        end
         si += delta
         ei += delta
-        increment_and_check_limit
       end
     end
   end

metadata

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