better_model 1.3.0 → 2.0.0

data/lib/better_model/schedulable/occurrence_calculator.rb

@@ -0,0 +1,1034 @@
+# frozen_string_literal: true
+
+module BetterModel
+  module Schedulable
+    # OccurrenceCalculator - Calcola occorrenze basate su regole di ricorrenza
+    #
+    # Questo è il cuore del sistema Schedulable. Prende una configurazione di schedule
+    # e calcola quando avvengono le occorrenze, rispettando eccezioni e vincoli.
+    #
+    class OccurrenceCalculator
+      attr_reader :config, :timezone
+
+      def initialize(config, timezone = "UTC")
+        # Convert string keys to symbols for easier access
+        @config = config.is_a?(Hash) ? config.with_indifferent_access : config
+        @timezone = ActiveSupport::TimeZone[timezone] || ActiveSupport::TimeZone["UTC"]
+      end
+
+      # Calcola la prossima occorrenza dopo un momento specifico
+      #
+      # @param after [Time] Momento di riferimento
+      # @return [Time, nil]
+      def next_occurrence(after: Time.current)
+        after = after.in_time_zone(@timezone)
+
+        # Controlla se siamo oltre ending_at
+        return nil if past_ending_date?(after)
+
+        # Genera candidati e trova il primo valido
+        candidates = generate_candidates(after, direction: :forward, limit: 1000)
+        candidates.find { |candidate| valid_occurrence?(candidate) && candidate > after }
+      end
+
+      # Calcola l'occorrenza precedente prima di un momento specifico
+      #
+      # @param before [Time] Momento di riferimento
+      # @return [Time, nil]
+      def previous_occurrence(before: Time.current)
+        before = before.in_time_zone(@timezone)
+
+        # Controlla se siamo prima di starting_from
+        return nil if before_starting_date?(before)
+
+        # Genera candidati e trova il primo valido
+        candidates = generate_candidates(before, direction: :backward, limit: 1000)
+        candidates.find { |candidate| valid_occurrence?(candidate) && candidate < before }
+      end
+
+      # Genera array di occorrenze in un range
+      #
+      # @param start_time [Time] Inizio range
+      # @param end_time [Time] Fine range
+      # @param limit [Integer] Limite occorrenze
+      # @return [Array<Time>]
+      def occurrences_between(start_time, end_time, limit: 100)
+        return [] if start_time.nil? || end_time.nil?
+
+        start_time = start_time.in_time_zone(@timezone)
+        end_time = end_time.in_time_zone(@timezone)
+
+        occurrences = []
+        current = start_time
+
+        while occurrences.size < limit && current <= end_time
+          next_occ = next_occurrence(after: current)
+          break unless next_occ
+          break if next_occ > end_time
+
+          occurrences << next_occ
+          current = next_occ + 1.second
+        end
+
+        occurrences
+      end
+
+      # Verifica se occorre in un momento specifico
+      #
+      # @param time [Time] Momento da verificare
+      # @return [Boolean]
+      def occurs_at?(time)
+        time = time.in_time_zone(@timezone)
+
+        # Se c'è duration, verifica se siamo dentro la durata
+        if config[:duration]
+          duration_seconds = config[:duration]
+          occurrence_start = find_occurrence_start_for(time)
+          return false unless occurrence_start
+
+          time >= occurrence_start && time < (occurrence_start + duration_seconds.seconds)
+        else
+          # Altrimenti deve matchare esattamente (o entro 1 minuto per tolleranza)
+          next_occ = next_occurrence(after: time - 1.minute)
+          return false unless next_occ
+
+          (time - next_occ).abs < 60 # Tolleranza 1 minuto
+        end
+      end
+
+      private
+
+      # Genera candidati per occorrenze
+      def generate_candidates(from_time, direction:, limit:)
+        frequency = config[:frequency]
+
+        base_candidates = case frequency
+        when "daily"
+          generate_daily_candidates(from_time, direction, limit)
+        when "every_n_days"
+          generate_every_n_days_candidates(from_time, direction, limit)
+        when "weekly"
+          generate_weekly_candidates(from_time, direction, limit)
+        when "biweekly"
+          generate_biweekly_candidates(from_time, direction, limit)
+        when "every_n_weeks"
+          generate_every_n_weeks_candidates(from_time, direction, limit)
+        when "monthly"
+          generate_monthly_candidates(from_time, direction, limit)
+        when "every_n_months"
+          generate_every_n_months_candidates(from_time, direction, limit)
+        when "yearly"
+          generate_yearly_candidates(from_time, direction, limit)
+        when "every_n_years"
+          generate_every_n_years_candidates(from_time, direction, limit)
+        when "every_n_hours"
+          generate_hourly_candidates(from_time, direction, limit)
+        when "every_n_minutes"
+          generate_minutely_candidates(from_time, direction, limit)
+        else
+          []
+        end
+
+        # Expand candidates with advance_by reminders if specified
+        expand_with_advance_reminders(base_candidates)
+      end
+
+      # Expands base occurrences with advance reminders
+      def expand_with_advance_reminders(base_candidates)
+        advance_by = config[:advance_by]
+        return base_candidates unless advance_by.present?
+
+        advance_offsets = Array(advance_by)
+        all_candidates = []
+
+        base_candidates.each do |base_time|
+          # Add all advance reminder times
+          advance_offsets.each do |offset_seconds|
+            reminder_time = base_time + offset_seconds.seconds
+            all_candidates << reminder_time
+          end
+        end
+
+        all_candidates.sort
+      end
+
+      # ========================================
+      # DAILY
+      # ========================================
+
+      def generate_daily_candidates(from_time, direction, limit)
+        times = config[:time] || ["00:00"]
+        candidates = []
+
+        if direction == :forward
+          current_date = from_time.to_date
+          days_checked = 0
+
+          while candidates.size < limit && days_checked < limit
+            times.each do |time_str|
+              candidate = parse_time_on_date(current_date, time_str)
+              candidates << candidate if candidate >= from_time
+            end
+
+            current_date += 1.day
+            days_checked += 1
+          end
+        else
+          current_date = from_time.to_date
+          days_checked = 0
+
+          while candidates.size < limit && days_checked < limit
+            times.reverse.each do |time_str|
+              candidate = parse_time_on_date(current_date, time_str)
+              candidates << candidate if candidate <= from_time
+            end
+
+            current_date -= 1.day
+            days_checked += 1
+          end
+        end
+
+        candidates
+      end
+
+      def generate_every_n_days_candidates(from_time, direction, limit)
+        interval = config[:interval] || 1
+        times = config[:time] || ["00:00"]
+        starting_from = config[:starting_from] ? (config[:starting_from].is_a?(String) ? Date.parse(config[:starting_from]) : config[:starting_from].to_date) : from_time.to_date
+
+        candidates = []
+
+        if direction == :forward
+          current_date = starting_from
+          # Avanza fino alla prima data >= from_time
+          while current_date < from_time.to_date
+            current_date += interval.days
+          end
+
+          while candidates.size < limit
+            times.each do |time_str|
+              candidate = parse_time_on_date(current_date, time_str)
+              candidates << candidate if candidate >= from_time
+            end
+
+            current_date += interval.days
+          end
+        else
+          # Backward - implementazione semplificata
+          current_date = from_time.to_date
+
+          while candidates.size < limit
+            times.reverse.each do |time_str|
+              candidate = parse_time_on_date(current_date, time_str)
+              candidates << candidate if candidate <= from_time
+            end
+
+            current_date -= interval.days
+          end
+        end
+
+        candidates
+      end
+
+      # ========================================
+      # WEEKLY
+      # ========================================
+
+      def generate_weekly_candidates(from_time, direction, limit)
+        weekdays = config[:weekday] || []
+        times = config[:time] || ["00:00"]
+
+        return [] if weekdays.empty?
+
+        candidates = []
+
+        if direction == :forward
+          current_date = from_time.to_date
+          days_checked = 0
+
+          while candidates.size < limit && days_checked < 365
+            day_name = current_date.strftime("%A").downcase
+            if weekdays.include?(day_name)
+              times.each do |time_str|
+                candidate = parse_time_on_date(current_date, time_str)
+                candidates << candidate if candidate >= from_time
+              end
+            end
+
+            current_date += 1.day
+            days_checked += 1
+          end
+        else
+          current_date = from_time.to_date
+          days_checked = 0
+
+          while candidates.size < limit && days_checked < 365
+            day_name = current_date.strftime("%A").downcase
+            if weekdays.include?(day_name)
+              times.reverse.each do |time_str|
+                candidate = parse_time_on_date(current_date, time_str)
+                candidates << candidate if candidate <= from_time
+              end
+            end
+
+            current_date -= 1.day
+            days_checked += 1
+          end
+        end
+
+        candidates
+      end
+
+      def generate_biweekly_candidates(from_time, direction, limit)
+        # Biweekly è every_n_weeks con interval 2
+        old_interval = config[:interval]
+        config[:interval] = 2
+        result = generate_every_n_weeks_candidates(from_time, direction, limit)
+        config[:interval] = old_interval
+        result
+      end
+
+      def generate_every_n_weeks_candidates(from_time, direction, limit)
+        interval = config[:interval] || 1
+        weekdays = config[:weekday] || []
+        times = config[:time] || ["00:00"]
+        starting_from = config[:starting_from] ? (config[:starting_from].is_a?(String) ? Date.parse(config[:starting_from]) : config[:starting_from].to_date) : from_time.to_date
+
+        return [] if weekdays.empty?
+
+        candidates = []
+
+        if direction == :forward
+          # Use the later of starting_from or from_time as the search start
+          search_from = [starting_from, from_time.to_date].max
+
+          # Trova la prima settimana >= search_from basata sul pattern di starting_from
+          base_week_start = starting_from.beginning_of_week
+          current_week_start = base_week_start
+
+          while current_week_start < search_from.beginning_of_week
+            current_week_start += interval.weeks
+          end
+
+          weeks_checked = 0
+          while candidates.size < limit && weeks_checked < 100
+            # Genera occorrenze per questa settimana
+            (0..6).each do |day_offset|
+              current_date = current_week_start + day_offset.days
+              day_name = current_date.strftime("%A").downcase
+
+              if weekdays.include?(day_name)
+                times.each do |time_str|
+                  candidate = parse_time_on_date(current_date, time_str)
+                  # Filter by both from_time AND starting_from
+                  candidates << candidate if candidate >= from_time && candidate.to_date >= starting_from
+                end
+              end
+            end
+
+            current_week_start += interval.weeks
+            weeks_checked += 1
+          end
+        else
+          # Backward
+          current_week_start = from_time.to_date.beginning_of_week
+          weeks_checked = 0
+
+          while candidates.size < limit && weeks_checked < 100
+            (0..6).reverse_each do |day_offset|
+              current_date = current_week_start + day_offset.days
+              day_name = current_date.strftime("%A").downcase
+
+              if weekdays.include?(day_name)
+                times.reverse.each do |time_str|
+                  candidate = parse_time_on_date(current_date, time_str)
+                  candidates << candidate if candidate <= from_time
+                end
+              end
+            end
+
+            current_week_start -= interval.weeks
+            weeks_checked += 1
+          end
+        end
+
+        candidates
+      end
+
+      # ========================================
+      # MONTHLY
+      # ========================================
+
+      def generate_monthly_candidates(from_time, direction, limit)
+        # Due modalità: day of month o weekday occurrence
+        if config[:day]
+          generate_monthly_by_day(from_time, direction, limit)
+        elsif config[:weekday] && config[:occurrence]
+          generate_monthly_by_weekday(from_time, direction, limit)
+        else
+          []
+        end
+      end
+
+      def generate_monthly_by_day(from_time, direction, limit)
+        days = config[:day]
+        times = config[:time] || ["00:00"]
+
+        candidates = []
+
+        if direction == :forward
+          current_date = from_time.to_date.beginning_of_month
+          months_checked = 0
+
+          while candidates.size < limit && months_checked < 120
+            days.each do |day|
+              actual_day = day_of_month(current_date.year, current_date.month, day)
+              next unless actual_day
+
+              date = Date.new(current_date.year, current_date.month, actual_day)
+
+              times.each do |time_str|
+                candidate = parse_time_on_date(date, time_str)
+                candidates << candidate if candidate >= from_time
+              end
+            end
+
+            current_date += 1.month
+            months_checked += 1
+          end
+        else
+          current_date = from_time.to_date.beginning_of_month
+          months_checked = 0
+
+          while candidates.size < limit && months_checked < 120
+            days.reverse.each do |day|
+              actual_day = day_of_month(current_date.year, current_date.month, day)
+              next unless actual_day
+
+              date = Date.new(current_date.year, current_date.month, actual_day)
+
+              times.reverse.each do |time_str|
+                candidate = parse_time_on_date(date, time_str)
+                candidates << candidate if candidate <= from_time
+              end
+            end
+
+            current_date -= 1.month
+            months_checked += 1
+          end
+        end
+
+        candidates
+      end
+
+      def generate_monthly_by_weekday(from_time, direction, limit)
+        weekdays = config[:weekday]
+        occurrence = config[:occurrence]
+        times = config[:time] || ["00:00"]
+
+        candidates = []
+
+        if direction == :forward
+          current_date = from_time.to_date.beginning_of_month
+          months_checked = 0
+
+          while candidates.size < limit && months_checked < 120
+            weekdays.each do |weekday_name|
+              date = nth_weekday_of_month(current_date.year, current_date.month, weekday_name, occurrence)
+              next unless date
+
+              times.each do |time_str|
+                candidate = parse_time_on_date(date, time_str)
+                candidates << candidate if candidate >= from_time
+              end
+            end
+
+            current_date += 1.month
+            months_checked += 1
+          end
+        else
+          current_date = from_time.to_date.beginning_of_month
+          months_checked = 0
+
+          while candidates.size < limit && months_checked < 120
+            weekdays.reverse.each do |weekday_name|
+              date = nth_weekday_of_month(current_date.year, current_date.month, weekday_name, occurrence)
+              next unless date
+
+              times.reverse.each do |time_str|
+                candidate = parse_time_on_date(date, time_str)
+                candidates << candidate if candidate <= from_time
+              end
+            end
+
+            current_date -= 1.month
+            months_checked += 1
+          end
+        end
+
+        candidates
+      end
+
+      def generate_every_n_months_candidates(from_time, direction, limit)
+        interval = config[:interval] || 1
+
+        # Determine the starting month for the pattern
+        base_date = if config[:starting_from]
+                      config[:starting_from].is_a?(String) ? Date.parse(config[:starting_from]) : config[:starting_from].to_date
+                    else
+                      # Use from_time's month as the base for additive pattern
+                      from_time.to_date
+                    end
+
+        candidates = []
+
+        # Salva interval originale e modifica temporaneamente per usare monthly logic
+        original_freq = config[:frequency]
+        config[:frequency] = "monthly"
+
+        if direction == :forward
+          # For every_n_months, skip current month and jump by interval
+          # Semantic: "every N months" means starting from NEXT interval period
+          # Example: From Nov 15, interval=2 → Jan (not Nov)
+          current_date = from_time.beginning_of_month + interval.months
+          months_checked = 0
+
+          while candidates.size < limit && months_checked < 100
+            # Generate all occurrences for this month
+            month_start = @timezone.parse("#{current_date} 00:00")
+            month_end = month_start.end_of_month
+
+            # Get all candidates in this month
+            month_candidates = generate_monthly_candidates(month_start, :forward, 100)
+                                 .select { |c| c >= month_start && c <= month_end }
+
+            # Add all candidates from this month
+            month_candidates.each do |candidate|
+              candidates << candidate
+              break if candidates.size >= limit
+            end
+
+            # Move to next valid month (add interval months)
+            current_date = current_date + interval.months
+            months_checked += 1
+          end
+        else
+          # Backward direction: subtract interval months iteratively
+          current_date = base_date.beginning_of_month
+          months_checked = 0
+
+          while candidates.size < limit && months_checked < 100
+            # Generate all occurrences for this month
+            month_start = @timezone.parse("#{current_date} 00:00")
+            month_end = month_start.end_of_month
+
+            # Get all candidates in this month
+            month_candidates = generate_monthly_candidates(month_start, :forward, 100)
+                                 .select { |c| c >= month_start && c <= month_end }
+                                 .reverse
+
+            # Add candidates that are before or equal to from_time
+            month_candidates.each do |candidate|
+              candidates << candidate if candidate <= from_time
+            end
+
+            # Move to previous valid month (subtract interval months)
+            current_date = current_date - interval.months
+            months_checked += 1
+          end
+        end
+
+        config[:frequency] = original_freq
+        candidates.first(limit)
+      end
+
+      # ========================================
+      # YEARLY
+      # ========================================
+
+      def generate_yearly_candidates(from_time, direction, limit)
+        dates = config[:date] || []
+        times = config[:time] || ["00:00"]
+
+        candidates = []
+
+        if direction == :forward
+          current_year = from_time.year
+          years_checked = 0
+
+          while candidates.size < limit && years_checked < 50
+            dates.each do |date_str|
+              month, day = date_str.split("-").map(&:to_i)
+              date = Date.new(current_year, month, day) rescue nil
+              next unless date
+
+              times.each do |time_str|
+                candidate = parse_time_on_date(date, time_str)
+                candidates << candidate if candidate > from_time
+              end
+            end
+
+            current_year += 1
+            years_checked += 1
+          end
+        else
+          current_year = from_time.year
+          years_checked = 0
+
+          while candidates.size < limit && years_checked < 50
+            dates.reverse.each do |date_str|
+              month, day = date_str.split("-").map(&:to_i)
+              date = Date.new(current_year, month, day) rescue nil
+              next unless date
+
+              times.reverse.each do |time_str|
+                candidate = parse_time_on_date(date, time_str)
+                candidates << candidate if candidate <= from_time
+              end
+            end
+
+            current_year -= 1
+            years_checked += 1
+          end
+        end
+
+        candidates
+      end
+
+      def generate_every_n_years_candidates(from_time, direction, limit)
+        interval = config[:interval] || 1
+        dates = config[:date] || []
+        times = config[:time] || ["00:00"]
+
+        candidates = []
+
+        if direction == :forward
+          # Determine base year - the anchor year for the pattern
+          # This must be consistent across all calls, not dependent on from_time
+          base_year = if config[:starting_from]
+                        starting_date = config[:starting_from].is_a?(String) ? Date.parse(config[:starting_from]) : config[:starting_from].to_date
+                        starting_date.year
+                      else
+                        # Use year 2000 as a universal base for patterns without starting_from
+                        # This ensures consistent interval calculation across all calls
+                        2000
+                      end
+
+          # Calculate first valid year >= from_time using the interval pattern
+          # Valid years are: base_year, base_year + interval, base_year + 2*interval, ...
+          # Find the smallest valid year >= from_time.year
+          years_diff = from_time.year - base_year
+          if years_diff >= 0
+            # from_time is after base_year, calculate how many intervals to skip
+            intervals_to_skip = (years_diff.to_f / interval).ceil
+            current_year = base_year + (intervals_to_skip * interval)
+          else
+            # from_time is before base_year, start from base_year
+            current_year = base_year
+          end
+
+          years_generated = 0
+          while candidates.size < limit && years_generated < 50
+            dates.each do |date_str|
+              month, day = date_str.split("-").map(&:to_i)
+              date = Date.new(current_year, month, day) rescue nil
+              next unless date
+
+              times.each do |time_str|
+                candidate = parse_time_on_date(date, time_str)
+                candidates << candidate if candidate > from_time
+              end
+            end
+
+            current_year += interval
+            years_generated += 1
+          end
+        else
+          current_year = from_time.year
+          years_generated = 0
+
+          while candidates.size < limit && years_generated < 50
+            dates.reverse.each do |date_str|
+              month, day = date_str.split("-").map(&:to_i)
+              date = Date.new(current_year, month, day)
+
+              times.reverse.each do |time_str|
+                candidate = parse_time_on_date(date, time_str)
+                candidates << candidate if candidate <= from_time
+              end
+            end
+
+            current_year -= interval
+            years_generated += 1
+          end
+        end
+
+        candidates
+      end
+
+      # ========================================
+      # HOURLY & MINUTELY
+      # ========================================
+
+      def generate_hourly_candidates(from_time, direction, limit)
+        interval = config[:interval] || 1
+        at_minutes = config[:at_minutes] || [0]
+
+        candidates = []
+
+        if direction == :forward
+          # Find next aligned hour slot (aligned to midnight)
+          # For interval=4: slots are at 00:00, 04:00, 08:00, 12:00, 16:00, 20:00
+          # But first check if there are remaining at_minutes in current aligned slot
+          current_hour = from_time.hour
+
+          # Find the current aligned hour slot
+          current_aligned_hour = (current_hour / interval) * interval
+
+          # Check if there are remaining minutes in the current aligned slot
+          at_minutes.each do |minute|
+            candidate = from_time.change(hour: current_aligned_hour, min: minute, sec: 0)
+            if candidate > from_time && within_time_range?(candidate)
+              candidates << candidate
+              break if candidates.size >= limit
+            end
+          end
+
+          # If we filled the limit with current slot, we're done
+          return candidates if candidates.size >= limit
+
+          # Calculate next aligned hour after current slot
+          next_aligned_hour = current_aligned_hour + interval
+
+          slots_checked = 0
+
+          while candidates.size < limit && slots_checked < 10000
+            # Handle hour wrapping to next days
+            effective_hour = next_aligned_hour + (slots_checked * interval)
+            days_to_add = effective_hour / 24
+            hour_in_day = effective_hour % 24
+
+            candidate_date = from_time.to_date + days_to_add.days
+
+            # Generate candidates for each at_minute in this hour slot
+            at_minutes.each do |minute|
+              candidate = candidate_date.in_time_zone(timezone).change(hour: hour_in_day, min: minute, sec: 0)
+
+              # Only add if it's after from_time and within time range
+              if candidate > from_time && within_time_range?(candidate)
+                candidates << candidate
+              end
+
+              break if candidates.size >= limit
+            end
+
+            slots_checked += 1
+          end
+        else
+          # Backward direction
+          current_time = from_time
+          hours_generated = 0
+
+          while candidates.size < limit && hours_generated < 1000
+            at_minutes.reverse.each do |minute|
+              candidate = current_time.change(min: minute, sec: 0)
+
+              if within_time_range?(candidate) && candidate <= from_time
+                candidates << candidate
+              end
+            end
+
+            current_time -= interval.hours
+            hours_generated += 1
+          end
+        end
+
+        candidates
+      end
+
+      def generate_minutely_candidates(from_time, direction, limit)
+        interval = config[:interval] || 1
+        time_range = config[:between]
+
+        candidates = []
+
+        if direction == :forward
+          current_date = from_time.to_date
+          days_checked = 0
+
+          while candidates.size < limit && days_checked < 100
+            # Determine the start time for this day
+            if time_range.is_a?(Array)
+              # Start from beginning of time range
+              start_hour_str = time_range[0]
+              day_start = @timezone.parse("#{current_date} #{start_hour_str}")
+            else
+              # Start from midnight
+              day_start = current_date.to_time.in_time_zone(@timezone)
+            end
+
+            # Generate minutely slots for this day at the interval
+            current_minute = 0
+            while current_minute < 1440  # 24 hours = 1440 minutes
+              slot_time = day_start + current_minute.minutes
+              candidate = slot_time.change(sec: 0)
+
+              # Check if it's valid (after from_time and within time range)
+              if candidate > from_time && within_time_range?(candidate)
+                candidates << candidate
+                break if candidates.size >= limit
+              end
+
+              break if candidates.size >= limit
+              current_minute += interval
+            end
+
+            current_date += 1.day
+            days_checked += 1
+          end
+        else
+          # Backward direction
+          current_time = from_time.change(sec: 0)
+          minutes_generated = 0
+
+          while candidates.size < limit && minutes_generated < 10000
+            if within_time_range?(current_time) && current_time <= from_time
+              candidates << current_time
+            end
+
+            current_time -= interval.minutes
+            minutes_generated += 1
+          end
+        end
+
+        candidates
+      end
+
+      # ========================================
+      # HELPER METHODS
+      # ========================================
+
+      def valid_occurrence?(time)
+        return false if before_starting_date?(time)
+        return false if past_ending_date?(time)
+        return false if within_time_range_defined? && !within_time_range?(time)
+        return false if matches_exception?(time)
+
+        true
+      end
+
+      def before_starting_date?(time)
+        return false unless config[:starting_from].present?
+
+        starting = case config[:starting_from]
+                   when String
+                     Date.parse(config[:starting_from])
+                   when Date
+                     config[:starting_from]
+                   when Time, ActiveSupport::TimeWithZone
+                     config[:starting_from].to_date
+                   else
+                     return false  # Unknown type, assume no constraint
+                   end
+        time.to_date < starting
+      rescue ArgumentError, TypeError => _e
+        # If we can't parse the starting_from, assume no constraint
+        Rails.logger.warn("Invalid starting_from value: #{config[:starting_from].inspect}") if defined?(Rails)
+        false
+      end
+
+      def past_ending_date?(time)
+        return false unless config[:ending_at].present?
+
+        ending = case config[:ending_at]
+                 when String
+                   Date.parse(config[:ending_at])
+                 when Date
+                   config[:ending_at]
+                 when Time, ActiveSupport::TimeWithZone
+                   config[:ending_at].to_date
+                 else
+                   return false  # Unknown type, assume no constraint
+                 end
+        time.to_date > ending
+      rescue ArgumentError, TypeError => _e
+        # If we can't parse the ending_at, assume no constraint
+        Rails.logger.warn("Invalid ending_at value: #{config[:ending_at].inspect}") if defined?(Rails)
+        false
+      end
+
+      def within_time_range_defined?
+        config[:between].present?
+      end
+
+      def within_time_range?(time)
+        return true unless config[:between]
+
+        range = config[:between]
+
+        # Se è un hash, è un date range
+        if range.is_a?(Hash)
+          return true unless range[:start].present? && range[:end].present?
+
+          start_date = case range[:start]
+                       when String
+                         Date.parse(range[:start])
+                       when Date
+                         range[:start]
+                       when Time, ActiveSupport::TimeWithZone
+                         range[:start].to_date
+                       else
+                         return true
+                       end
+          end_date = case range[:end]
+                     when String
+                       Date.parse(range[:end])
+                     when Date
+                       range[:end]
+                     when Time, ActiveSupport::TimeWithZone
+                       range[:end].to_date
+                     else
+                       return true
+                     end
+          return time.to_date >= start_date && time.to_date <= end_date
+        end
+
+        # Altrimenti è un time range (es: ['08:00', '18:00'])
+        # End time is EXCLUSIVE (between means >= start and < end)
+        if range.is_a?(Array) && range.size == 2
+          start_time_str, end_time_str = range
+          start_hour, start_min = start_time_str.split(":").map(&:to_i)
+          end_hour, end_min = end_time_str.split(":").map(&:to_i)
+
+          time_in_seconds = time.hour * 3600 + time.min * 60
+          start_in_seconds = start_hour * 3600 + start_min * 60
+          end_in_seconds = end_hour * 3600 + end_min * 60
+
+          return time_in_seconds >= start_in_seconds && time_in_seconds < end_in_seconds
+        end
+
+        true
+      end
+
+      def matches_exception?(time)
+        exceptions = config[:exceptions]
+        return false unless exceptions
+
+        # Exception: weekdays
+        if exceptions[:weekdays]
+          weekday_name = time.strftime("%A").downcase
+          return true if exceptions[:weekdays].include?(weekday_name)
+        end
+
+        # Exception: specific dates
+        if exceptions[:dates]
+          # Support both full date format (YYYY-MM-DD) and short format (MM-DD)
+          full_date_str = time.strftime("%Y-%m-%d")
+          short_date_str = time.strftime("%m-%d")
+          month_day_str = time.strftime("%-m-%-d")  # Without leading zeros
+
+          return true if exceptions[:dates].include?(full_date_str)
+          return true if exceptions[:dates].include?(short_date_str)
+          return true if exceptions[:dates].include?(month_day_str)
+        end
+
+        # Exception: months
+        if exceptions[:months]
+          return true if exceptions[:months].include?(time.month)
+        end
+
+        # Exception: patterns (first friday, etc.)
+        if exceptions[:patterns]
+          exceptions[:patterns].each do |pattern|
+            return true if matches_exception_pattern?(time, pattern)
+          end
+        end
+
+        false
+      end
+
+      def matches_exception_pattern?(time, pattern)
+        if pattern[:weekday] && pattern[:occurrence]
+          weekday_name = pattern[:weekday].to_s
+          occurrence = pattern[:occurrence]
+
+          # Verifica se time è l'N-esimo weekday del mese
+          expected_date = nth_weekday_of_month(time.year, time.month, weekday_name, occurrence)
+          return time.to_date == expected_date
+        end
+
+        false
+      end
+
+      def parse_time_on_date(date, time_str)
+        hour, minute = time_str.split(":").map(&:to_i)
+        @timezone.local(date.year, date.month, date.day, hour, minute, 0)
+      end
+
+      def day_of_month(year, month, day_spec)
+        if day_spec > 0
+          # Positivo: giorno dal primo (1, 2, 3, ...)
+          last_day = Date.new(year, month, -1).day
+          return nil if day_spec > last_day
+          day_spec
+        else
+          # Negativo: giorno dalla fine (-1 = ultimo, -2 = penultimo, ...)
+          last_day = Date.new(year, month, -1).day
+          actual_day = last_day + day_spec + 1
+          return nil if actual_day < 1
+          actual_day
+        end
+      end
+
+      def nth_weekday_of_month(year, month, weekday_name, occurrence)
+        weekday_num = Date::DAYNAMES.map(&:downcase).index(weekday_name)
+        return nil unless weekday_num
+
+        if occurrence > 0
+          # Primo, secondo, terzo, ...
+          first_day = Date.new(year, month, 1)
+          first_weekday = first_day
+
+          # Trova il primo weekday_name del mese
+          while first_weekday.wday != weekday_num
+            first_weekday += 1.day
+          end
+
+          # Aggiungi (occurrence - 1) settimane
+          result = first_weekday + (occurrence - 1).weeks
+
+          # Verifica che sia ancora nello stesso mese
+          return nil if result.month != month
+
+          result
+        else
+          # Ultimo, penultimo, ...
+          last_day = Date.new(year, month, -1)
+          last_weekday = last_day
+
+          # Trova l'ultimo weekday_name del mese
+          while last_weekday.wday != weekday_num
+            last_weekday -= 1.day
+          end
+
+          # Sottrai settimane
+          result = last_weekday + (occurrence + 1).weeks
+
+          # Verifica che sia ancora nello stesso mese
+          return nil if result.month != month
+
+          result
+        end
+      end
+
+      def find_occurrence_start_for(time)
+        # Trova l'occorrenza che inizia prima o uguale a time
+        # Questo è usato per duration check
+        prev = previous_occurrence(before: time + 1.second)
+        return prev if prev && prev <= time
+
+        nil
+      end
+    end
+  end
+end