better_model 1.2.0 → 2.0.0

data/lib/better_model/schedulable/schedule_builder.rb

@@ -0,0 +1,269 @@
+# frozen_string_literal: true
+
+module BetterModel
+  module Schedulable
+    # ScheduleBuilder - DSL per costruire configurazioni di schedule
+    #
+    # Questo builder implementa il DSL fluent per definire pattern di ricorrenza,
+    # eccezioni, e vincoli temporali.
+    #
+    # Esempio:
+    #   builder = ScheduleBuilder.new(event)
+    #   builder.recurs(:daily) do
+    #     at ['09:00']
+    #     except weekday: [:saturday]
+    #   end
+    #
+    class ScheduleBuilder
+      attr_reader :record, :config
+
+      VALID_FREQUENCIES = %w[
+        daily every_n_days
+        weekly biweekly every_n_weeks
+        monthly every_n_months
+        yearly every_n_years
+        every_n_hours every_n_minutes
+      ].freeze
+
+      def initialize(record)
+        @record = record
+        @config = {}
+        @recurrence_builder = nil
+      end
+
+      # Definisce un pattern di ricorrenza
+      #
+      # @param frequency [Symbol] :daily, :weekly, :monthly, :yearly, :every_n_days, etc.
+      # @yield [builder] Blocco per configurare il pattern
+      def recurs(frequency, &block)
+        freq_str = frequency.to_s
+        unless VALID_FREQUENCIES.include?(freq_str)
+          raise ArgumentError, "Invalid frequency: '#{frequency}'. Valid options: #{VALID_FREQUENCIES.join(', ')}"
+        end
+
+        @config[:frequency] = freq_str
+
+        # Crea builder per la ricorrenza specifica
+        @recurrence_builder = RecurrenceBuilder.new(@config)
+
+        # Supporta due stili:
+        # 1. Con parametro: s.recurs(:daily) {|r| r.at [...] }
+        # 2. Senza parametro: s.recurs(:daily) { at [...] }
+        if block_given?
+          # DEBUG
+          # puts "Block arity: #{block.arity}"
+
+          if block.arity.zero?
+            # Nessun parametro → usa instance_eval
+            @recurrence_builder.instance_eval(&block)
+          else
+            # Con parametro → yield normale
+            yield @recurrence_builder
+          end
+        end
+
+        self
+      end
+
+      # Converte in hash per serializzazione
+      def to_h
+        @config
+      end
+
+      # RecurrenceBuilder - Builder interno per pattern di ricorrenza
+      class RecurrenceBuilder
+        VALID_WEEKDAYS = %w[monday tuesday wednesday thursday friday saturday sunday].freeze
+
+        def initialize(config)
+          @config = config
+        end
+
+        # Imposta gli orari
+        # @param times [Array<String>] Array di orari tipo ['09:00', '15:00']
+        def at(times)
+          times_array = Array(times)
+          times_array.each do |time_str|
+            unless valid_time_format?(time_str)
+              raise ArgumentError, "Invalid time format: '#{time_str}'. Expected HH:MM (00:00-23:59)"
+            end
+          end
+          @config[:time] = times_array
+        end
+
+        # Imposta i vincoli sui giorni
+        # @option options [Array<Symbol>] :weekday Giorni della settimana [:monday, :friday]
+        # @option options [Array<Integer>] :day Giorni del mese [1, 15, -1]
+        # @option options [Array<String>] :date Date annuali ['03-15', '12-25']
+        # @option options [Integer] :occurrence N-esimo giorno (per monthly)
+        def on(**options)
+          if options[:weekday]
+            weekdays = Array(options[:weekday]).map(&:to_s)
+            invalid = weekdays - VALID_WEEKDAYS
+
+            if invalid.any?
+              raise ArgumentError, "Invalid weekdays: #{invalid.join(', ')}. Valid options: #{VALID_WEEKDAYS.join(', ')}"
+            end
+
+            @config[:weekday] = weekdays
+
+            # Se c'è occurrence, è monthly con N-esimo weekday
+            if options[:occurrence]
+              @config[:occurrence] = options[:occurrence]
+            end
+          end
+
+          if options[:day]
+            @config[:day] = Array(options[:day])
+          end
+
+          if options[:date]
+            dates = Array(options[:date])
+            dates.each do |date_str|
+              unless valid_date_format?(date_str)
+                raise ArgumentError, "Invalid date format: '#{date_str}'. Expected MM-DD (e.g., '03-15', '12-25')"
+              end
+            end
+            @config[:date] = dates
+          end
+        end
+
+        # Imposta intervallo (per every_n_days, every_n_weeks, etc.)
+        # @param value [Integer] Numero di giorni/settimane/mesi/ore/minuti
+        def interval(value)
+          int_value = value.to_i
+          raise ArgumentError, "Interval must be a positive integer, got: #{value}" if int_value <= 0
+          @config[:interval] = int_value
+        end
+
+        # Imposta range temporale
+        # @param start_time [String, Time, Array] Inizio (o array di time range)
+        # @param end_time [String, Time] Fine
+        def between(start_time, end_time = nil)
+          if end_time
+            # Range orario o date range
+            @config[:between] = {
+              start: start_time.is_a?(String) ? start_time : start_time.iso8601,
+              end: end_time.is_a?(String) ? end_time : end_time.iso8601
+            }
+          else
+            # Solo orario range (array)
+            if start_time.is_a?(Array)
+              # Validate time format for array ranges
+              start_time.each do |time_str|
+                next unless time_str.is_a?(String)
+                unless valid_time_format?(time_str)
+                  raise ArgumentError, "Invalid time format in between range: '#{time_str}'. Expected HH:MM (00:00-23:59)"
+                end
+              end
+            end
+            @config[:between] = start_time
+          end
+        end
+
+        # Imposta durata evento
+        # @param duration [ActiveSupport::Duration] Durata
+        def duration(duration)
+          @config[:duration] = duration.to_i  # Salva in secondi
+        end
+
+        # Imposta data di inizio
+        # @param date [String, Date] Data di inizio
+        def starting_from(date)
+          date_str = date.is_a?(String) ? date : date.to_s
+
+          # Validate date format
+          begin
+            Date.parse(date_str) if date_str.is_a?(String)
+          rescue ArgumentError => e
+            raise ArgumentError, "Invalid starting_from date format: '#{date_str}'. #{e.message}"
+          end
+
+          @config[:starting_from] = date_str
+        end
+
+        # Imposta data di fine
+        # @param date [String, Date] Data di fine
+        def ending_at(date)
+          @config[:ending_at] = date.is_a?(String) ? date : date.to_s
+        end
+
+        # Alias per ending_at
+        def for_duration(duration)
+          starting = @config[:starting_from] || Time.current.to_date.to_s
+          ending = (Date.parse(starting) + duration).to_s
+          ending_at(ending)
+        end
+
+        # Imposta minuti specifici (per hourly)
+        # @param minutes [Array<Integer>] Minuti [0, 30]
+        def at_minutes(minutes)
+          @config[:at_minutes] = Array(minutes)
+        end
+
+        # Imposta reminder anticipato
+        # @param advance [Integer, Array<Integer>] Giorni prima (negativi)
+        def advance_by(advance)
+          @config[:advance_by] = Array(advance).map { |v| v.is_a?(Integer) ? v : v.to_i }
+        end
+
+        # Imposta eccezioni
+        # @option options [Array<Symbol>] :weekday Giorni da escludere
+        # @option options [Array<String>] :date Date da escludere
+        # @option options [Array<Integer>] :month Mesi da escludere
+        # @option options [Hash] :pattern Pattern complessi
+        def except(**options)
+          @config[:exceptions] ||= {}
+
+          if options[:weekday]
+            @config[:exceptions][:weekdays] ||= []
+            @config[:exceptions][:weekdays] += Array(options[:weekday]).map(&:to_s)
+            @config[:exceptions][:weekdays].uniq!
+          end
+
+          if options[:date]
+            @config[:exceptions][:dates] ||= []
+            @config[:exceptions][:dates] += Array(options[:date])
+            @config[:exceptions][:dates].uniq!
+          end
+
+          if options[:month]
+            @config[:exceptions][:months] ||= []
+            @config[:exceptions][:months] += Array(options[:month])
+            @config[:exceptions][:months].uniq!
+          end
+
+          if options[:pattern]
+            @config[:exceptions][:patterns] ||= []
+            @config[:exceptions][:patterns] << options[:pattern]
+          end
+        end
+
+        private
+
+        # Valida formato time HH:MM
+        def valid_time_format?(time_str)
+          return false unless time_str.is_a?(String)
+          return false unless time_str.match?(/^\d{1,2}:\d{2}$/)
+
+          hour, minute = time_str.split(":").map(&:to_i)
+          hour.between?(0, 23) && minute.between?(0, 59)
+        end
+
+        # Valida formato date MM-DD
+        def valid_date_format?(date_str)
+          return false unless date_str.is_a?(String)
+          return false unless date_str.match?(/^\d{1,2}-\d{1,2}$/)
+
+          month, day = date_str.split("-").map(&:to_i)
+          return false unless month.between?(1, 12)
+
+          # Usa anno bisestile (2024) per validare giorni in febbraio
+          Date.new(2024, month, day)
+          true
+        rescue ArgumentError
+          false
+        end
+      end
+    end
+  end
+end

data/lib/better_model/schedulable.rb

@@ -0,0 +1,356 @@
+# frozen_string_literal: true
+
+# Schedulable - Sistema di schedulazione ricorrente per modelli Rails
+#
+# Questo concern permette di definire schedule ricorrenti con pattern complessi,
+# eccezioni, e calcolo automatico delle occorrenze.
+#
+# APPROCCIO OPT-IN: La schedulazione non è attiva automaticamente.
+# Devi chiamare esplicitamente `schedulable do...end` nel tuo modello.
+#
+# REQUISITI DATABASE:
+#   - Colonna per salvare la configurazione schedule (JSONB o TEXT con serialize)
+#   - Colonna opzionale per timezone per-record
+#   - Colonna opzionale per cache next_occurrence_at
+#
+# Esempio di utilizzo:
+#   class Event < ApplicationRecord
+#     include BetterModel
+#
+#     serialize :schedule_config, coder: JSON, type: Hash
+#
+#     schedulable do
+#       schedule_field :schedule_config
+#       timezone_field :timezone
+#     end
+#   end
+#
+#   # Per-record scheduling
+#   event = Event.create!(name: "Stand-up Meeting")
+#   event.schedule do |s|
+#     s.recurs :weekly do
+#       s.on weekday: [:monday]
+#       s.at ['09:00']
+#     end
+#   end
+#
+#   event.next_occurrence           # => 2025-11-10 09:00:00 +0100
+#   event.due_now?                  # => true/false
+#   Event.due_now                   # => [events due now]
+#
+module BetterModel
+  module Schedulable
+    extend ActiveSupport::Concern
+
+    included do
+      # Validazione ActiveRecord
+      unless ancestors.include?(ActiveRecord::Base)
+        raise ArgumentError, "BetterModel::Schedulable can only be included in ActiveRecord models"
+      end
+
+      # Configurazione schedulable (opt-in)
+      class_attribute :schedulable_enabled, default: false
+      class_attribute :schedulable_config, default: nil
+
+      # Auto-update next_occurrence_at when schedule changes
+      after_save :auto_update_next_occurrence, if: :schedulable_enabled?
+    end
+
+    class_methods do
+      # DSL per attivare e configurare schedulable (OPT-IN)
+      #
+      # @example Attivazione base
+      #   schedulable do
+      #     schedule_field :schedule_config
+      #     timezone_field :timezone
+      #   end
+      #
+      def schedulable(&block)
+        # Attiva schedulable
+        self.schedulable_enabled = true
+
+        # Configura se passato un blocco
+        if block_given?
+          config = Configuration.new
+          config.instance_eval(&block)
+          self.schedulable_config = config.freeze
+        end
+
+        # Valida configurazione
+        validate_schedulable_config!
+      end
+
+      # Verifica se schedulable è attivo
+      def schedulable_enabled?
+        schedulable_enabled == true
+      end
+
+      # Trova tutti i record dovuti ora
+      #
+      # @param tolerance [ActiveSupport::Duration] Finestra di tolleranza
+      # @return [Array] Array of records (not ActiveRecord::Relation for now)
+      def due_now(tolerance: 5.minutes)
+        return [] unless schedulable_enabled?
+
+        # For now, use in-memory filtering to ensure accuracy with travel_to
+        # TODO: Optimize with next_occurrence_at cache for production
+        all.select { |record| record.due_now?(tolerance: tolerance) }
+      end
+
+      # Trova i prossimi N eventi in programma
+      #
+      # @param limit [Integer] Numero massimo di risultati
+      # @return [Array] Array of records sorted by next_occurrence_at
+      def upcoming(limit: 10)
+        return [] unless schedulable_enabled?
+
+        results = all.map do |record|
+          next_occ = record.next_occurrence
+          next unless next_occ
+
+          { event: record, occurrence: next_occ }
+        end.compact
+
+        results.sort_by { |r| r[:occurrence] }.first(limit)
+      end
+
+      # Trova eventi in ritardo (oltre grace period)
+      #
+      # @param grace_period [ActiveSupport::Duration] Periodo di grazia
+      # @return [Array]
+      def overdue(grace_period: 1.hour)
+        return [] unless schedulable_enabled?
+
+        # For now, use in-memory filtering to ensure accuracy with travel_to
+        # TODO: Optimize with next_occurrence_at cache for production
+        now = Time.current
+
+        all.select do |record|
+          # Get the last occurrence that should have happened
+          last_occ = record.previous_occurrence(before: now)
+          next unless last_occ
+
+          # Also get the next upcoming occurrence
+          next_occ = record.next_occurrence(after: now)
+          next unless next_occ
+
+          # Overdue if:
+          # 1. Last occurrence is beyond grace period
+          # 2. Last occurrence is closer to now than next occurrence (it was "recent")
+          past_dist = now - last_occ
+          future_dist = next_occ - now
+
+          last_occ < (now - grace_period) && past_dist < future_dist
+        end
+      end
+
+      private
+
+      def validate_schedulable_config!
+        config = schedulable_config
+        return unless config
+
+        # Valida che i campi esistano
+        schedule_field = config.schedule_field
+        unless column_names.include?(schedule_field.to_s)
+          raise ArgumentError, "Schedule field #{schedule_field} does not exist in #{table_name}"
+        end
+
+        if config.timezone_field
+          unless column_names.include?(config.timezone_field.to_s)
+            raise ArgumentError, "Timezone field #{config.timezone_field} does not exist in #{table_name}"
+          end
+        end
+      end
+    end
+
+    # ============================================================================
+    # INSTANCE METHODS
+    # ============================================================================
+
+    # DSL per configurare lo schedule del record
+    #
+    # @example
+    #   event.schedule do |s|
+    #     s.recurs :daily do
+    #       s.at ['09:00']
+    #     end
+    #   end
+    #
+    def schedule(&block)
+      raise SchedulableNotEnabledError unless self.class.schedulable_enabled?
+
+      builder = ScheduleBuilder.new(self)
+      yield builder if block_given?
+
+      # Salva configurazione
+      schedule_field = self.class.schedulable_config.schedule_field
+      self[schedule_field] = builder.to_h
+
+      if persisted?
+        save!
+        update_next_occurrence!
+      end
+    end
+
+    # Calcola la prossima occorrenza dopo un momento specifico
+    #
+    # @param after [Time] Momento di riferimento (default: Time.current)
+    # @return [Time, nil]
+    def next_occurrence(after: Time.current)
+      raise SchedulableNotEnabledError unless self.class.schedulable_enabled?
+
+      schedule_config = get_schedule_config
+      return nil if schedule_config.blank?
+
+      calculator = OccurrenceCalculator.new(schedule_config, record_timezone)
+      calculator.next_occurrence(after: after)
+    end
+
+    # Calcola l'occorrenza precedente prima di un momento specifico
+    #
+    # @param before [Time] Momento di riferimento (default: Time.current)
+    # @return [Time, nil]
+    def previous_occurrence(before: Time.current)
+      raise SchedulableNotEnabledError unless self.class.schedulable_enabled?
+
+      schedule_config = get_schedule_config
+      return nil if schedule_config.blank?
+
+      calculator = OccurrenceCalculator.new(schedule_config, record_timezone)
+      calculator.previous_occurrence(before: before)
+    end
+
+    # Genera array di occorrenze in un range temporale
+    #
+    # @param start_time [Time] Inizio range
+    # @param end_time [Time] Fine range
+    # @param limit [Integer] Limite numero occorrenze
+    # @return [Array<Time>]
+    def occurrences_between(start_time, end_time, limit: 100)
+      raise SchedulableNotEnabledError unless self.class.schedulable_enabled?
+
+      schedule_config = get_schedule_config
+      return [] if schedule_config.blank?
+
+      calculator = OccurrenceCalculator.new(schedule_config, record_timezone)
+      calculator.occurrences_between(start_time, end_time, limit: limit)
+    end
+
+    # Verifica se l'evento occorre in un momento specifico
+    #
+    # @param time [Time] Momento da verificare
+    # @return [Boolean]
+    def occurs_at?(time)
+      raise SchedulableNotEnabledError unless self.class.schedulable_enabled?
+
+      schedule_config = get_schedule_config
+      return false if schedule_config.blank?
+
+      calculator = OccurrenceCalculator.new(schedule_config, record_timezone)
+      calculator.occurs_at?(time)
+    end
+
+    # Verifica se l'evento è dovuto ora (entro finestra di tolleranza)
+    #
+    # @param tolerance [ActiveSupport::Duration] Finestra di tolleranza
+    # @return [Boolean]
+    def due_now?(tolerance: 5.minutes)
+      raise SchedulableNotEnabledError unless self.class.schedulable_enabled?
+
+      now = Time.current
+
+      # Check if next occurrence is within tolerance window (forward or backward)
+      # This handles both: event happening now AND event coming up soon
+      next_occ = next_occurrence(after: now - tolerance)
+      return false unless next_occ
+
+      next_occ <= (now + tolerance)
+    end
+
+    # Aggiorna la cache next_occurrence_at (se la colonna esiste)
+    def update_next_occurrence!
+      return unless self.class.schedulable_enabled?
+      return unless respond_to?(:next_occurrence_at=)
+
+      next_occ = next_occurrence
+      update_column(:next_occurrence_at, next_occ)
+    end
+
+    # Callback: auto-update next_occurrence_at after save
+    def auto_update_next_occurrence
+      return unless respond_to?(:next_occurrence_at=)
+
+      # Check if schedule_config changed
+      schedule_field = self.class.schedulable_config.schedule_field
+      if saved_change_to_attribute?(schedule_field)
+        next_occ = next_occurrence
+        update_column(:next_occurrence_at, next_occ)
+      end
+    end
+
+    # Restituisce una descrizione leggibile dello schedule
+    #
+    # @return [String]
+    def schedule_summary
+      raise SchedulableNotEnabledError unless self.class.schedulable_enabled?
+
+      schedule_config = get_schedule_config
+      return "No schedule configured" if schedule_config.blank?
+
+      # TODO: Implementare formatter human-readable
+      schedule_config.inspect
+    end
+
+    private
+
+    def get_schedule_config
+      schedule_field = self.class.schedulable_config.schedule_field
+      config = self[schedule_field]
+
+      # Gestisci sia Hash che String (se serializzato)
+      return config if config.is_a?(Hash)
+      return JSON.parse(config) if config.is_a?(String)
+
+      {}
+    rescue JSON::ParserError
+      {}
+    end
+
+    def record_timezone
+      timezone_field = self.class.schedulable_config&.timezone_field
+      return "UTC" unless timezone_field
+
+      self[timezone_field] || "UTC"
+    end
+  end
+
+  # Configurazione Schedulable
+  class Schedulable::Configuration
+    def initialize
+      @schedule_field = :schedule_config
+      @timezone_field = nil
+    end
+
+    # Dual-purpose getter/setter for schedule_field
+    def schedule_field(field_name = nil)
+      return @schedule_field if field_name.nil?
+      @schedule_field = field_name.to_sym
+    end
+
+    # Dual-purpose getter/setter for timezone_field
+    def timezone_field(field_name = nil)
+      return @timezone_field if field_name.nil?
+      @timezone_field = field_name.to_sym
+    end
+  end
+
+  # Errori custom
+  class SchedulableError < StandardError; end
+
+  class SchedulableNotEnabledError < SchedulableError
+    def initialize(msg = nil)
+      super(msg || "Schedulable is not enabled. Add 'schedulable do...end' to your model.")
+    end
+  end
+end

data/lib/better_model/searchable.rb

@@ -227,13 +227,13 @@ module BetterModel
           next if value.nil?
           next if value.respond_to?(:empty?) && value.empty?
 
-          # Apply scope
-          scope = if value == true || value == "true"
-            scope.public_send(predicate_scope)
-          elsif value.is_a?(Array)
+          # v2.0.0: ALL predicates require parameters
+          # Apply scope with parameter
+          scope = if value.is_a?(Array)
             # Splat array values for predicates like _between that expect multiple args
             scope.public_send(predicate_scope, *value)
           else
+            # Pass value as parameter (all predicates require at least one parameter)
             scope.public_send(predicate_scope, value)
           end
         end