has_helpers 5.0.2

data/lib/has_helpers/active_record/base.rb

@@ -0,0 +1,50 @@
+# typed: false
+# frozen_string_literal: true
+
+require "active_record"
+
+module HasHelpers
+  module ActiveRecord
+    class ServiceError < ::StandardError; end
+
+    module Base
+      def to_service(url: nil, **options)
+        begin
+          url ||= ::HasHelpers::BasePresenter::Routing.routes.polymorphic_path(self)
+        rescue
+          raise ServiceError, $!.message
+        end
+        name.to_s.to_service(url, **options)
+      end
+
+      def to_renderable(*args)
+        if ::HasHelpers::ActiveRecord::Base.to_renderable_proc
+          proc_result = ::HasHelpers::ActiveRecord::Base.to_renderable_proc.call(self)
+        end
+
+        proc_result || to_service(*args)
+      rescue ServiceError
+        name.to_s.to_text_node
+      end
+
+      # Set a proc which will process the current object when #to_renderable
+      # is invoked. If the proc does not handle the object (by returning nil)
+      # then the default logic will take effect.
+      #
+      #=== Examples
+      #   HasHelpers::ActiveRecord::Base.set_renderable_proc do |object|
+      #     # logic here
+      #   end
+      #
+      #   HasHelpers::ActiveRecord::Base.set_renderable_proc = proc { |object| #logic here }
+      def self.set_renderable_proc(to_renderable_proc = nil, &block)
+        @to_renderable_proc = to_renderable_proc || block
+      end
+
+      def self.to_renderable_proc
+        @to_renderable_proc
+      end
+    end
+  end
+end
+::ActiveRecord::Base.include(::HasHelpers::ActiveRecord::Base)

data/lib/has_helpers/active_record/date_range.rb

@@ -0,0 +1,228 @@
+# typed: false
+# frozen_string_literal: true
+
+module HasHelpers
+  module ActiveRecord
+    module DateRange
+      END_DATE_SANITY_ERR_MSG = "%s must not be before the %s"
+      DATE_RANGE_OVERLAP_ERR_MSG = "must be unique within the given date range"
+
+      # Adds validations to prevent records from having date ranges which are inverted --
+      # with the end date before the start date.
+      #
+      # In addition to validations calling +has_valid_date_range+ creates:
+      # * An accessor method which returns a range created from the start and end dates. See
+      #   the +:as+ option.
+      #
+      #=== Examples
+      #   has_valid_date_range(
+      #     start_attr: :start_date,
+      #     end_attr: :end_date,
+      #     as: :date_range
+      #   )
+      #
+      #=== Options
+      # +:as+:              Determines the name of the accessor method which is created by
+      #                     +has_valid_date_range+. The accessor method returns a range created from
+      #                     the start and end dates. Defaults to +:date_range+.
+      #
+      # default_start_date  Since we need the star_attr to not always be initialized when it arrives
+      #                     empty, we add this option
+
+      def has_valid_date_range(
+        start_attr: :start_date,
+        end_attr: :end_date,
+        as: :date_range,
+        default_start_date: true
+      )
+        # Normalize start_date. Set it to the current date if nil.
+        before_validation do
+          send("#{ start_attr }=", Date.current) if send(start_attr).nil? && default_start_date
+        end
+
+        # Define an accessor method which returns the date range for the given date options.
+        # The name of this method may be customized by passing a value to the :as option,
+        # which is by default +:date_range+.
+        #
+        #=== Examples
+        #   class Schedule
+        #     has_valid_date_range
+        #   end
+        #
+        #   schedule = Schedule.new(
+        #     start_date: "2015-05-04",
+        #     end_date: "2015-12-22"
+        #   )
+        #   schedule.date_range      # => #<Date: 2015-05-04>..#<Date: 2015-12-22>
+        unless method_defined?(as)
+          define_method(as) do
+            (DateRange.start_date_or_default(send(start_attr))..DateRange.end_date_or_default(send(end_attr)))
+          end
+        end
+
+        # Validate that the end date does not precede the start date.
+        validate do
+          errors.add(end_attr, END_DATE_SANITY_ERR_MSG % [end_attr.to_s.humanize.titleize, start_attr.to_s.humanize.titleize]) if DateRange.end_date_or_default(send(end_attr)) < DateRange.start_date_or_default(send(start_attr))
+        end
+      end
+
+      # Adds validations to prevent records from having date ranges which overlap. These
+      # validations can be scoped to the uniqueness of any number of attributes by using the
+      # strict and nullable scope options. The current record is validated against other
+      # records provided by the +:siblings+ option.
+      #
+      # In addition to validations calling +has_distinct_date_range+ creates:
+      # * A scope for accessing records with date ranges covering a particular date. See the
+      #   +:scope_name+ option.
+      #
+      # Finally, +has_distinct_date_range+ includes everything from +has_valid_date_range+.
+      #
+      #== Siblings
+      #
+      # Siblings are the related records against which the validation will be checked.
+      # I.e. these are all the records which the current record potentially conflicts
+      # with.
+      #
+      # The default siblings options is a proc which gets the `owner` of the current
+      # record and then gets all the sibling records from the owner. The siblings
+      # records are taken to be records from a scoped association (by default this
+      # is named `current_<base_association_name>`) plus any additional records from
+      # the base association (duplicates excluded), where the `base_association_name`
+      # is generated from the class name of the current object. It is up to the user
+      # to define such a scope on the owner class. If a scoped association does not
+      # exist or has no records cached in memory, then the sibling records are sourced
+      # from the base association.
+      #
+      # If any portion of the siblings logic needs to be overridden then it must be
+      # overridden in its entirety.
+      #
+      #=== Examples
+      #   has_distinct_date_range(
+      #     start_attr: :start_date,
+      #     end_attr: :end_date,
+      #     strict_scopes: :user_id,
+      #     nullable_scopes: [:product_type_id, :product_category_id],
+      #     siblings: -> { owner.others },
+      #     as: :date_range
+      #   )
+      #
+      #   # Same as the previous example, but the start, end and siblings parameters are
+      #   # omitted because the default values are sufficient.
+      #   has_distinct_date_range(
+      #     strict_scopes: :user_id,
+      #     nullable_scopes: [:product_type_id, :product_category_id]
+      #   )
+      #
+      #=== Options
+      # +:strict_scopes+:   Attributes which should match during overlap checks if both sides are equal.
+      # +:nullable_scopes+: These are the same as +:strict_scopes+ except they match when both sides are
+      #                     equal or either side is nil.
+      # +:siblings+:        A collection or proc which returns a collection of objects amongst which the
+      #                     current object should be unique considering the given date range and scopes.
+      # +:as+:              Determines the name of the accessor method which is created by
+      #                     +has_distinct_date_range+. The accessor method returns a range created from
+      #                     the start and end dates. Defaults to +:date_range+.
+      # +:scope_name+:      Determines the name of the ActiveRecord scope created by
+      #                     +has_distinct_date_range+ which returns the records which have a date range
+      #                     which covers the given date. Defaults to +:current+.
+
+      def has_distinct_date_range(
+        start_attr: :start_date,
+        end_attr: :end_date,
+        strict_scopes: [],
+        nullable_scopes: [],
+        siblings: nil,
+        as: :date_range,
+        scope_name: nil
+      )
+        strict_s = Array(strict_scopes)
+        nullable_s = Array(nullable_scopes)
+
+        ## distinct date ranges have to be valid date ranges
+        has_valid_date_range(start_attr: start_attr, end_attr: end_attr, as: as)
+
+        date_range_accessor_name = as
+
+        # Method which accepts another object and determines whether it overlaps with
+        # the current object, considering all defined scopes.
+        #
+        #=== Examples
+        #   object.date_range_overlaps?(other)
+        overlap_method_name = "#{ as }_overlaps?"
+        unless method_defined?(overlap_method_name)
+          define_method(overlap_method_name) do |other, strict_scopes: strict_s, nullable_scopes: nullable_s|
+            # An object overlaps if all of the following conditions are true
+            # with respect to the current object:
+
+            # * Ids are _not_ equal, or if ids are nil then other is the same as self.
+            ((id.nil? && other.id.nil?) ? !self.equal?(other) : id != other.id) &&
+
+              # * Date ranges overlap
+              send(date_range_accessor_name).overlaps?(other.send(date_range_accessor_name)) &&
+
+              # * Strict scopes are all equal
+              strict_scopes.all? { |attr| send(attr) == other.send(attr) } &&
+
+              # * Nullable scopes all either are equal or have at least one side which is nil.
+              nullable_scopes.all? { |attr| send(attr) == other.send(attr) || send(attr).nil? || other.send(attr).nil? }
+          end
+        end
+
+        # Add a scope which returns the records which have a date range which covers the given
+        # date (defaults to the current date), i.e. records which  are "current" on the given date.
+        #
+        #=== Examples
+        #   class Schedule
+        #     has_distinct_date_range
+        #   end
+        #
+        #   Schedule.current  # => Returns all Schedules whose date range covers the current date.
+        scope_name ||= (as == :date_range) ? :current : "current_for_#{ as }"
+        base_association_name = self.base_class.name.demodulize.tableize
+        scope scope_name, ->(date = Date.current) do
+          where("daterange(:date, :date, '[]') && daterange(#{base_association_name}.#{ start_attr }, #{base_association_name}.#{ end_attr }, '[]')", date: date)
+        end
+
+        # Validate that the date range for this object does not overlap with the
+        # date range of any of its siblings.
+        siblings ||= proc {
+          scoped_association_name = "#{ scope_name }_#{ base_association_name }"
+          if owner
+            # Search for siblings.
+            # If a scoped association exists and there are records in-memory for that
+            # association then return those records plus any additional records from
+            # the base association (excluding duplicates).
+            if owner.class.reflect_on_association(scoped_association_name) && owner.send(scoped_association_name).target.any?
+              scoped_siblings = owner.send(scoped_association_name)
+              scoped_siblings + owner.send(base_association_name).reject { |sibling| scoped_siblings.include?(sibling) }
+            else
+              # No scoped association exists, or the scoped association has no in-memory records.
+              owner.send(base_association_name)
+            end
+          end
+        }
+        validate do
+          if !marked_for_destruction?
+            s = (siblings.respond_to?(:call) ? instance_eval(&siblings.to_proc) : siblings)
+
+            is_sibling_overlap = s.any? { |sibling| send(overlap_method_name, sibling) } if s
+
+            if is_sibling_overlap
+              all_scopes = strict_s + nullable_s
+              error_msg = "#{ all_scopes.map(&:to_s).map(&:humanize).to_sentence }#{ " " unless all_scopes.empty? }#{ DATE_RANGE_OVERLAP_ERR_MSG }"
+              errors.add(start_attr, error_msg)
+            end
+          end
+        end
+      end
+
+      def self.start_date_or_default(date)
+        date || -::Date::Infinity.new
+      end
+
+      def self.end_date_or_default(date)
+        date || ::Date::Infinity.new
+      end
+    end
+  end
+end

data/lib/has_helpers/active_record/nested_resource.rb

@@ -0,0 +1,58 @@
+# typed: false
+# frozen_string_literal: true
+
+# Each model which includes NestedResource should define an `owner`
+# instance method or declare `has_owner` (see the has_owner gem).
+module HasHelpers
+  module ActiveRecord
+    module NestedResource
+      def self.included(klass)
+        klass.prepend(PrependedMethods)
+      end
+
+      # Generate a service with a nested URL, where the base is generated
+      # using the current object's owner.
+      def to_service(
+        use_base_class: false, # Use the base class instance of the current object. Only applies to STI models.
+        owner_instance: owner,
+        action: :edit,
+        resources: [
+          *action,
+          owner_instance,
+          use_base_class ? self.becomes(self.class.base_class) : self
+        ],
+        **options
+      )
+        route_name_parts = []
+        route_resources = []
+
+        resources.each do |resource|
+          case resource
+          when String, Symbol
+            route_name_parts << resource
+          else
+            route_name_parts << resource.class.name.demodulize.underscore
+            route_resources << resource
+          end
+        end
+
+        route_name = "#{ route_name_parts.join("_") }_path"
+        super(
+          url: ::HasHelpers::BasePresenter::Routing.routes.send(route_name, *route_resources),
+          **options
+        )
+      end
+
+      module PrependedMethods
+        def name
+          super
+        rescue
+          # Rescuing is expensive, but there is no other accurate solution.
+          # Maybe we should avoid falling back to this case by having each
+          # nested resource define name, and allowing this case to fail.
+          self.class.name.titleize
+        end
+      end
+    end
+  end
+end

data/lib/has_helpers/active_record/validation.rb

@@ -0,0 +1,63 @@
+# typed: false
+# frozen_string_literal: true
+
+module HasHelpers
+  module ActiveRecord
+    module Validation
+      # === Options
+      # [:attribute]
+      #   When given an accessor reader method will be created with the given name.
+      #   Also, errors will be assigned to this attribute instead of those passed in the arguments.
+      #
+      # [:allow_none]
+      #   When this option is set, then the presence of one of the given attributes is not required.
+      #
+      # === Examples
+      #   scopes_xor :amount, :percent
+      #   socpes_xor :advisor_id, :user_id, :firm_id, :company_id, :attribute => :owner
+      def scopes_xor(*args)
+        options = args.extract_options!
+
+        # Add validation to ensure that exactly one of the given attributes is set.
+        validate do
+          number_of_attrs_set = args.sum { |arg| send(arg) ? 1 : 0 }
+          if number_of_attrs_set == 0 && !options[:allow_none]
+            Array(options[:attribute] || args).each do |attr|
+              errors[attr] << "Must be assigned one of " + args.map { |arg| arg.to_s.humanize }.to_sentence(last_word_connector: " or ")
+            end
+          elsif number_of_attrs_set > 1
+            Array(options[:attribute] || args).each do |attr|
+              errors[attr] << "May be assigned to only one of " + args.map { |arg| arg.to_s.humanize }.to_sentence(last_word_connector: " or ")
+            end
+          end
+        end
+
+        # Create a accessor reader method for the given attribute name (if any).
+        if options[:attribute]
+          define_method(options[:attribute]) do
+            args.lazy.map { |attr| send(attr.to_s.remove(/_id$/)) }.detect(&:identity)
+          end
+
+          # Returns the attribute name for the current owner, which may be a foreign_key for belongs_to associations, e.g. "advisor_id".
+          define_method("#{ options[:attribute] }_attribute") do
+            args.detect { |attr| send(attr) }
+          end
+        end
+      end
+
+      # Adds validations to require at least on of the given attributes.
+      # === Examples
+      #   scopes_one_or_more :product_class, :product_type, :product_category
+      def self.scopes_one_or_more(*args)
+        options = args.extract_options!
+        validate do
+          unless args.any? { |attr| send(attr) } # Check that at least one of the attributes is set
+            Array(options[:attribute] || args).each do |attr|
+              errors[attr] << "Must set one of " + args.map { |arg| arg.to_s.humanize }.to_sentence(last_word_connector: " or ")
+            end
+          end
+        end
+      end
+    end
+  end
+end