active_manageable 0.1.0

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/active_manageable.gemspec

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+# load a file relative to the current location
+require_relative "lib/active_manageable/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "active_manageable"
+  spec.version = ActiveManageable::VERSION
+  spec.authors = ["Chris Hilton", "Chris Branson"]
+  spec.email = ["449774+chrismhilton@users.noreply.github.com", "138595+chrisbranson@users.noreply.github.com"]
+
+  spec.summary = "Business logic framework for Ruby on Rails"
+  spec.description = "Framework for business logic classes in a Ruby on Rails application"
+  spec.homepage = "https://github.com/CircleSD/active_manageable"
+  spec.license = "MIT"
+
+  # Minimum version of Ruby compatible with Rails 7.0
+  spec.required_ruby_version = ">= 2.7.0"
+
+  # Metadata used on gem’s profile page on rubygems.org
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "https://github.com/CircleSD/active_manageable/blob/main/CHANGELOG.md"
+  spec.metadata["bug_tracker_uri"] = "https://github.com/CircleSD/active_manageable/issues"
+  spec.metadata["documentation_uri"] = spec.homepage
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+
+  # Binary folder where the gem’s executables are located
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+
+  # Add lib directory to $LOAD_PATH to make code available via the require statement
+  spec.require_paths = ["lib"]
+
+  # Register runtime and development dependencies
+  # including gems that are essential to test and build this gem
+
+  # rails dependencies
+  spec.add_dependency "activerecord", ">= 6.0"
+  spec.add_dependency "activesupport", ">= 6.0"
+
+  # gem dependencies
+  spec.add_dependency "rails-i18n"
+  spec.add_dependency "flexitime", "~> 1.0"
+
+  # test dependencies
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "appraisal"
+  spec.add_development_dependency "sqlite3", "~> 1.4.0"
+  spec.add_development_dependency "rspec-rails"
+  spec.add_development_dependency "rails-controller-testing"
+  spec.add_development_dependency "factory_bot_rails"
+  spec.add_development_dependency "shoulda-matchers"
+  spec.add_development_dependency "simplecov"
+
+  # test modules
+  spec.add_development_dependency "pundit"
+  spec.add_development_dependency "cancancan"
+  spec.add_development_dependency "ransack"
+  spec.add_development_dependency "kaminari"
+
+  # linter dependencies
+  spec.add_development_dependency "rubocop", "1.23.0"
+  spec.add_development_dependency "standard"
+  spec.add_development_dependency "rubocop-rails"
+  spec.add_development_dependency "rubocop-rspec"
+
+  # For more information and examples about making a new gem, checkout our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "active_manageable"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/gemfiles/.bundle/config

@@ -0,0 +1,2 @@
+---
+BUNDLE_RETRY: "1"

data/gemfiles/rails_6_0.gemfile

@@ -0,0 +1,8 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "activerecord", "~> 6.0.1"
+gem "activesupport", "~> 6.0.1"
+
+gemspec path: "../"

data/gemfiles/rails_6_1.gemfile

@@ -0,0 +1,8 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "activerecord", "~> 6.1"
+gem "activesupport", "~> 6.1"
+
+gemspec path: "../"

data/gemfiles/rails_7_0.gemfile

@@ -0,0 +1,8 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "activerecord", "~> 7.0"
+gem "activesupport", "~> 7.0"
+
+gemspec path: "../"

data/lib/active_manageable/authorization/cancancan.rb

@@ -0,0 +1,28 @@
+#
+# Authorization methods for CanCanCan
+# https://github.com/CanCanCommunity/cancancan
+#
+module ActiveManageable
+  module Authorization
+    module CanCanCan
+      extend ActiveSupport::Concern
+
+      included do
+        private
+
+        def authorize(record:, action: nil)
+          action ||= @current_method
+          current_ability.authorize!(action, record)
+        end
+
+        def scoped_class
+          model_class.accessible_by(current_ability)
+        end
+
+        def current_ability
+          ::Ability.new(current_user)
+        end
+      end
+    end
+  end
+end

data/lib/active_manageable/authorization/pundit.rb

@@ -0,0 +1,28 @@
+#
+# Authorization methods for Pundit
+# https://github.com/varvet/pundit
+#
+module ActiveManageable
+  module Authorization
+    module Pundit
+      extend ActiveSupport::Concern
+
+      included do
+        private
+
+        def authorize(record:, action: nil)
+          action ||= authorize_action
+          ::Pundit.authorize(current_user, record, action)
+        end
+
+        def scoped_class
+          ::Pundit.policy_scope(current_user, model_class)
+        end
+
+        def authorize_action
+          "#{@current_method}?".to_sym
+        end
+      end
+    end
+  end
+end

data/lib/active_manageable/base.rb

@@ -0,0 +1,218 @@
+module ActiveManageable
+  class Base
+    class_attribute :model_class, instance_writer: false, instance_predicate: false
+    class_attribute :defaults, instance_writer: false, instance_predicate: false
+    class_attribute :module_initialize_state_methods, instance_writer: false, instance_predicate: false
+
+    attr_reader :target, :current_method, :attributes, :options
+
+    # target provides a common variable to use within the CRUD, auxiliary & library methods
+    # whereas the object & collection methods provide less ambiguous external access
+    alias_method :object, :target
+    alias_method :collection, :target
+
+    class << self
+      # Ruby method called when a child class inherits from a parent class
+      def inherited(subclass)
+        super
+        # necessary to set default value here rather than in class_attribute declaration
+        # otherwise all subclasses share the same hash/array instance
+        subclass.defaults = {}
+        subclass.module_initialize_state_methods = []
+      end
+
+      delegate :current_user, to: ActiveManageable
+
+      # Include the required action methods in your class
+      # either all methods using the ActiveManageable::ALL_METHODS constant
+      # or selective methods from :index, :show, :new, :create, :edit, :update, :destroy
+      # and optionally set the :model_class
+      #
+      # For example:-
+      #   manageable ActiveManageable::ALL_METHODS
+      #   manageable ActiveManageable::ALL_METHODS, model_class: Album
+      #   manageable :index, :show
+      def manageable(*methods)
+        options = methods.extract_options!.dup
+
+        methods = ActiveManageable::Methods.constants if methods[0] == ActiveManageable::ALL_METHODS
+
+        methods.each do |method|
+          include ActiveManageable::Methods.const_get(method.to_s.classify)
+        end
+
+        include_authorization
+        include_search
+        include_pagination
+
+        options.each { |key, value| send(:"#{key}=", value) }
+
+        set_model_class
+      end
+
+      private
+
+      def include_authorization
+        case ActiveManageable.configuration.authorization_library
+        when :pundit
+          include ActiveManageable::Authorization::Pundit
+        when :cancancan
+          include ActiveManageable::Authorization::CanCanCan
+        end
+      end
+
+      def include_search
+        case ActiveManageable.configuration.search_library
+        when :ransack
+          include ActiveManageable::Search::Ransack
+        end
+      end
+
+      def include_pagination
+        case ActiveManageable.configuration.pagination_library
+        when :kaminari
+          include ActiveManageable::Pagination::Kaminari
+        end
+      end
+
+      def set_model_class
+        self.model_class ||= begin
+          if name.end_with?(ActiveManageable.configuration.subclass_suffix)
+            name.chomp(ActiveManageable.configuration.subclass_suffix).classify.constantize
+          end
+        rescue NameError
+        end
+      end
+
+      def initialize_state_methods(*methods)
+        module_initialize_state_methods.concat(methods)
+      end
+
+      def add_method_defaults(key:, value:, methods:)
+        methods = Array(methods).map(&:to_sym)
+        methods << :all if methods.empty?
+        defaults[key] ||= {}
+        methods.each { |method| defaults[key][method] = value }
+      end
+    end
+
+    def current_user
+      @current_user || ActiveManageable.current_user
+    end
+
+    def with_current_user(user)
+      @current_user = user
+      yield
+    ensure
+      @current_user = nil
+    end
+
+    private
+
+    def initialize_state(attributes: {}, options: {})
+      @target = nil
+      @current_method = calling_method
+      @attributes = normalize_attributes(state_argument_to_hwia(attributes))
+      @options = state_argument_to_hwia(options)
+      module_initialize_state_methods.each { |method| send(method) }
+    end
+
+    def authorize(record:, action: nil)
+    end
+
+    # Returns the name of the calling method
+    # using caller_locations that returns the current execution stack
+    # and catering for inheritance and two occurrences of initialize_state in the execution stack
+    # when the ransack module is included as it has its own definition of the method that calls super
+    # https://www.lucascaton.com.br/2016/11/04/ruby-how-to-get-the-name-of-the-calling-method
+    def calling_method
+      my_caller = caller_locations(1..1).first.label
+      caller_locations[1..].find { |location| location.label != my_caller }.label.to_sym
+    end
+
+    # Converts a state argument to a ActiveSupport::HashWithIndifferentAccess.
+    # The purpose of the method is to return a duplicate object for arguments like the attributes
+    # so that any changes that are made internally do not affect the source object.
+    #
+    # For a Hash returns an ActiveSupport::HashWithIndifferentAccess.
+    # For a ActiveSupport::HashWithIndifferentAccess returns a duplicate ActiveSupport::HashWithIndifferentAccess.
+    # For an ActionController::Parameters returns a safe ActiveSupport::HashWithIndifferentAccess
+    # representation of the parameters with all unpermitted keys removed.
+    #
+    # NB: For an ActionController::Parameters we experimented with using the deep_dup method
+    # to return a duplicate ActionController::Parameters but this caused issues
+    # for the attributes argument when the params had been permiited and then nested params are replaced with a hash.
+    # That would be fine if the attributes were then used for mass assignment, however,
+    # first we call normalize_attribute_values which uses the each method
+    # which converts all hashes into ActionController::Parameters with the permitted attribute set to false
+    # so when performing mass assignment that resulted in a ActiveModel::ForbiddenAttributesError.
+    def state_argument_to_hwia(arg)
+      case arg
+      when Hash
+        arg.with_indifferent_access
+      when action_controller_params?
+        arg.to_h
+      else
+        arg
+      end
+    end
+
+    # Returns true if the object is an ActionController::Parameters
+    # using class.name so the gem does not need a dependency on ActionPack simply for a case statement
+    def action_controller_params?
+      ->(object) { object.class.name == "ActionController::Parameters" }
+    end
+
+    def normalize_attributes(attributes)
+      normalize_attribute_values(model_class, attributes)
+    end
+
+    # Parse date & datetime attribute values and normalize decimal separator for numeric attributes
+    def normalize_attribute_values(model_class, attributes)
+      case attributes
+      when Hash
+        attributes.each do |key, value|
+          if key.end_with?("_attributes")
+            association_class = model_association_class(model_class, key.delete_suffix("_attributes"))
+            normalize_attribute_values(association_class, value) if association_class.present?
+          else
+            case model_attribute_type(model_class, key)
+            when :date
+              attributes[key] = Flexitime.parse(value).try(:to_date) || value
+            when :datetime
+              attributes[key] = Flexitime.parse(value) || value
+            when :decimal, :float
+              attributes[key] = normalize_decimal_separator(value)
+            end
+          end
+        end
+      when Array
+        attributes.each { |attrs| normalize_attribute_values(model_class, attrs) }
+      end
+    end
+
+    def model_association_class(model_class, association_name)
+      model_class.reflect_on_association(association_name).try(:class_name).try(:constantize)
+    end
+
+    # Returns the type of the attribute with the given name
+    # and could be overridden by a child class in order to
+    # return the type of both column and non-column based attributes
+    # when a non-column based attribute value needed to be normalized
+    def model_attribute_type(model_class, attribute_name)
+      model_class.type_for_attribute(attribute_name).type
+    end
+
+    # Returns a value with a comma separator replaced with a point separator
+    def normalize_decimal_separator(value)
+      normalize_decimal_separator?(value) ? value.tr(",", ".") : value
+    end
+
+    # Normalize decimal separator when the locale number separator is a comma
+    # and the value does not include a point and includes only one comma
+    def normalize_decimal_separator?(value)
+      I18n.t("number.format.separator") == "," &&
+        value.to_s.count(".") == 0 && value.to_s.count(",") == 1
+    end
+  end
+end

data/lib/active_manageable/configuration.rb

@@ -0,0 +1,58 @@
+module ActiveManageable
+  AUTHORIZATION_LIBRARIES = %i[pundit cancancan].freeze
+  SEARCH_LIBRARIES = %i[ransack].freeze
+  PAGINATION_LIBRARIES = %i[kaminari].freeze
+  LOADING_METHODS = %i[includes preload eager_load].freeze
+
+  class Configuration
+    attr_reader :authorization_library, :search_library, :pagination_library, :default_loading_method
+    attr_accessor :subclass_suffix
+
+    def initialize
+      @default_loading_method = :includes
+      @subclass_suffix = "Manager"
+    end
+
+    def authorization_library=(authorization_library)
+      raise ArgumentError.new("Invalid authorization library") unless authorization_library_valid?(authorization_library)
+      @authorization_library = authorization_library.to_sym
+    end
+
+    def search_library=(search_library)
+      raise ArgumentError.new("Invalid search library") unless search_library_valid?(search_library)
+      @search_library = search_library.to_sym
+    end
+
+    def pagination_library=(pagination_library)
+      raise ArgumentError.new("Invalid pagination library") unless pagination_library_valid?(pagination_library)
+      @pagination_library = pagination_library.to_sym
+    end
+
+    def default_loading_method=(default_loading_method)
+      raise ArgumentError.new("Invalid method for eager loading") unless default_loading_method_valid?(default_loading_method)
+      @default_loading_method = default_loading_method.to_sym
+    end
+
+    private
+
+    def authorization_library_valid?(authorization_library)
+      option_valid?(AUTHORIZATION_LIBRARIES, authorization_library)
+    end
+
+    def search_library_valid?(search_library)
+      option_valid?(SEARCH_LIBRARIES, search_library)
+    end
+
+    def pagination_library_valid?(pagination_library)
+      option_valid?(PAGINATION_LIBRARIES, pagination_library)
+    end
+
+    def default_loading_method_valid?(default_loading_method)
+      option_valid?(LOADING_METHODS, default_loading_method)
+    end
+
+    def option_valid?(options, option)
+      option.present? && options.include?(option.to_s.to_sym)
+    end
+  end
+end

data/lib/active_manageable/methods/auxiliary/includes.rb

@@ -0,0 +1,98 @@
+module ActiveManageable
+  module Methods
+    module Auxiliary
+      module Includes
+        extend ActiveSupport::Concern
+
+        class_methods do
+          # Sets the default associations to eager load when fetching records
+          # in the index, show, edit, update and destroy methods
+          # if the methods :options argument does not contain a :includes key;
+          # accepting a single, array or hash of association names;
+          # optional :methods in which to eager load the associations;
+          # and optional :loading_method if this needs to be different to the configuration :default_loading_method
+          # also accepting a lambda/proc to execute to return association names and optional :methods
+          #
+          # For example:-
+          #   default_includes :songs
+          #   default_includes :songs, :artist, methods: :show
+          #   default_includes songs: :artist, loading_method: :eager_load, methods: [:index, :edit]
+          #   default_includes -> { includes_associations }
+          #   default_includes -> { includes_associations }, methods: [:index, :edit]
+          def default_includes(*associations)
+            options = extract_includes_options!(associations)
+            loading_method = options[:loading_method] || ActiveManageable.configuration.default_loading_method
+            assoc = associations.first.is_a?(Proc) ? associations.first : associations
+            value = {associations: assoc, loading_method: loading_method}
+            add_method_defaults(key: :includes, value: value, methods: options[:methods])
+          end
+
+          private
+
+          # As the associations argument may contain a single hash containing both
+          # the associations and options we cannot use the array extract_options! method
+          # as this removes the last element in the array if it's a hash.
+          #
+          # For example :-
+          # default_includes songs: :artist, loading_method: :preload, methods: :index
+          # results in an argument value of :-
+          # [{:songs=>:artist, :loading_method=>:preload, :methods=>:index}]
+          #
+          # So instead this method, like extract_options!, ascertains
+          # if the last element in the array is a hash but then it extracts
+          # the specific options and only removes the last element if it's empty.
+          # Therefore catering for the variety of association formats
+          # and potential presence of the options eg.
+          #
+          # [:songs, :artist, {:loading_method=>:preload, :methods=>"index"}]
+          # [:artist, {:songs=>:artist}, {:loading_method=>:preload, :methods=>:index}]
+          # [{:songs=>:artist, :loading_method=>:preload, :methods=>:index}]
+          def extract_includes_options!(associations)
+            if associations.last.is_a?(Hash)
+              options = associations.last.extract!(:loading_method, :methods)
+              associations.pop if associations.last.empty?
+              options
+            else
+              {}
+            end
+          end
+        end
+
+        included do
+          private
+
+          # Accepts either an array/hash of associations
+          # or a hash with associations and loading_method keys
+          # so it's possible to specify loading_method on a per request basis.
+          # Uses associations and loading_method from opts
+          # or defaults for the method or defaults for all methods
+          # or configuration default loading_method.
+          def includes(opts)
+            unless opts.is_a?(Hash) && opts.key?(:associations)
+              opts = {associations: opts}
+            end
+            associations = opts[:associations] || get_default_includes_associations
+            if associations.present?
+              loading_method = opts[:loading_method] || get_default_includes_loading_method
+              @target = @target.send(loading_method, associations)
+            else
+              @target
+            end
+          end
+
+          def get_default_includes_associations
+            includes = defaults[:includes] || {}
+            associations = includes.dig(@current_method, :associations) || includes.dig(:all, :associations)
+            associations.is_a?(Proc) ? instance_exec(&associations) : associations
+          end
+
+          def get_default_includes_loading_method
+            includes = defaults[:includes] || {}
+            loading_method = includes.dig(@current_method, :loading_method) || includes.dig(:all, :loading_method)
+            loading_method || ActiveManageable.configuration.default_loading_method
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_manageable/methods/auxiliary/model_attributes.rb

@@ -0,0 +1,59 @@
+module ActiveManageable
+  module Methods
+    module Auxiliary
+      module ModelAttributes
+        extend ActiveSupport::Concern
+
+        class_methods do
+          # Sets the default attribute values to use when building a model object
+          # in the new and create methods and these defaults are combined with
+          # the attribute values from the methods :attributes argument;
+          # accepting either a hash of attribute values or a lambda/proc
+          # to execute to return a hash of attribute values;
+          # and optional :methods in which to use the attribute values.
+          #
+          # For example:-
+          #   default_attribute_values genre: "pop"
+          #   default_attribute_values genre: "pop", released_at: Date.current, methods: :new
+          #   default_attribute_values -> { default_attrs }
+          #   default_attribute_values -> { default_attrs }, methods: [:new, :create]
+          def default_attribute_values(*attributes)
+            case attributes.first
+            when Hash
+              # when the argument contains a hash - extract the methods from the hash
+              # attributes value [{:name=>"Dark Side of the Moon", :genre=>"rock", :methods=>:create}]
+              methods = attributes.first.delete(:methods)
+            when Proc
+              # when the argument contains a lambda/proc - extract the methods from the array
+              # attributes value [#<Proc:0x0000000110174c90 ... (lambda)>, {:methods=>:create}]
+              methods = attributes.extract_options![:methods]
+            end
+            attrs = attributes.first
+            add_method_defaults(key: :attributes, value: attrs, methods: methods)
+          end
+        end
+
+        included do
+          private
+
+          # Returns attribute values to use in the new and create methods
+          # consisting of a merge of the method attributes argument
+          # and class defaults with the method argument taking precedence
+          def attribute_values
+            @attributes.is_a?(Hash) ? @attributes.reverse_merge(get_default_attribute_values) : @attributes
+          end
+
+          # Get the default attribute values for the method
+          # from the class attribute that can contain a hash of attribute values
+          # or a lambda/proc to execute to return attribute values
+          def get_default_attribute_values
+            default_attributes = defaults[:attributes] || {}
+            attributes = default_attributes[@current_method] || default_attributes[:all] || {}
+            attributes = (instance_exec(&attributes) || {}) if attributes.is_a?(Proc)
+            attributes.with_indifferent_access
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_manageable/methods/auxiliary/order.rb

@@ -0,0 +1,43 @@
+module ActiveManageable
+  module Methods
+    module Auxiliary
+      module Order
+        extend ActiveSupport::Concern
+
+        class_methods do
+          # Sets the default order to use when fetching records in the index method
+          # if the index :options argument does not contain an :order key;
+          # accepting attributes in the same formats as the ActiveRecord order method
+          # or a lambda/proc to execute to return attributes in the recognised formats.
+          #
+          # For example:-
+          #   default_order :name
+          #   default_order "name DESC"
+          #   default_order -> { order_attributes }
+          def default_order(*attributes)
+            defaults[:order] = attributes.first.is_a?(Proc) ? attributes.first : attributes
+          end
+        end
+
+        included do
+          private
+
+          def order(attributes)
+            @target = @target.order(get_order_attributes(attributes))
+          end
+
+          def get_order_attributes(attributes)
+            attributes || get_default_order_attributes
+          end
+
+          # Get the default order attributes from the class attribute
+          # that can contain an array of attribute names or name & direction strings
+          # or a lambda/proc to execute to return an array of attribute names
+          def get_default_order_attributes
+            defaults[:order].is_a?(Proc) ? instance_exec(&defaults[:order]) : defaults[:order]
+          end
+        end
+      end
+    end
+  end
+end