resourcerer 1.0.0 → 2.0.3

data/lib/resourcerer.rb

@@ -1,5 +1,14 @@
-require 'resourcerer/resourceable'
+# frozen_string_literal: true
 
-ActiveSupport.on_load(:action_controller) do
-  include Resourcerer::Resourceable
+require 'resourcerer/version'
+require 'active_support/all'
+
+module Resourcerer
+  autoload :Configuration, 'resourcerer/configuration'
+  autoload :Controller,    'resourcerer/controller'
+  autoload :Resource,      'resourcerer/resource'
+
+  ActiveSupport.on_load :action_controller do
+    include Controller
+  end
 end

data/lib/resourcerer/configuration.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module Resourcerer
+  # Internal: Normalizes configuration options by providing common shortcuts for
+  # certain options. These shortcuts make the library easier to use.
+  #
+  # Examples:
+  #   find_by: :name     ->(name, collection) { collection.find_by(name: name)}
+  #   assign?: :update   -> { action_name == 'update' }
+  #   id: :person_id     -> { params[:person_id] }
+  class Configuration
+    # Public: Available configuration options for a Resource.
+    OPTIONS = [
+      :assign,
+      :assign?,
+      :attrs,
+      :build,
+      :collection,
+      :find,
+      :find_by,
+      :id,
+      :model,
+      :permit,
+    ].freeze
+
+    attr_reader :options
+
+    # Public: Normalizes configuration options for a Resource, ensuring every
+    # relevant option is assigned a Proc.
+    #
+    # options - Config Hash for the new Resource. See OPTIONS.
+    # block   - If supplied, the block is executed to provide options.
+    #
+    # Returns a Hash where every value is a Proc.
+    def initialize(options, &block)
+      @options = options
+      instance_eval(&block) if block_given?
+
+      assert_incompatible_options_pair :find_by, :find
+      assert_incompatible_options_pair :permit, :attrs
+
+      normalize_assign_option
+      normalize_attrs_option
+      normalize_find_by_option
+      normalize_id_option
+      normalize_model_option
+      normalize_permit_option
+
+      assert_proc_options *OPTIONS
+    end
+
+    # Public: Applies the configuration to the specified options.
+    # Does not override an option if it had previously been specified.
+    #
+    # Returns the updated configuration options.
+    def apply(other_options)
+      other_options.reverse_merge!(options)
+    end
+
+    # Internal: Every option can also be specified in the block, DSL-style.
+    #
+    # Each generated method captures the value of an option.
+    OPTIONS.each do |name|
+      define_method(name) do |arg = nil, &block|
+        options[name] = arg || block
+      end
+    end
+
+  private
+
+
+    # Internal: Normalizes the `find_by` option to be a `find` Proc.
+    #
+    # Example:
+    #   find_by: :name  ->(name, collection) { collection.find_by(name: name)}
+    def normalize_find_by_option
+      if find_by = options.delete(:find_by)
+        options[:find] = ->(id, scope) { scope.find_by!(find_by => id) }
+      end
+    end
+
+    # Internal: Normalizes the `permit` option to be a Proc.
+    #
+    # Example:
+    #   permit: [:name]  -> { [:name] }
+    def normalize_permit_option
+      option_to_proc :permit do |*fields|
+        -> { fields }
+      end
+    end
+
+    # Internal: Normalizes the `assign?` option to be a Proc.
+    #
+    # Example:
+    #   assign?: false  -> { false }
+    #   assign?: :update  -> { action_name == 'update' }
+    #   assign?: [:edit, :update]  -> { action_name.in?(['edit', 'update']) }
+    def normalize_assign_option
+      bool = options[:assign?]
+      options[:assign?] = -> { bool } if bool == !!bool
+
+      option_to_proc :assign? do |*actions|
+        actions = Set.new(actions.map(&:to_s))
+        -> { actions.member?(action_name) }
+      end
+    end
+
+    # Internal: Normalizes the `attrs` option to be a Proc.
+    #
+    # Example:
+    #   attrs: :person_params  -> { person_params }
+    def normalize_attrs_option
+      option_to_proc :attrs do |params_method|
+        -> { send(params_method) }
+      end
+    end
+
+    # Internal: Normalizes the `id` option to be a Proc.
+    #
+    # Example:
+    #   id: :person_id  -> { params[:person_id] }
+    def normalize_id_option
+      option_to_proc :id do |*ids|
+        -> { ids.map { |id| params[id] }.find(&:present?) }
+      end
+    end
+
+    # Internal: Normalizes the `model` option to be a Proc.
+    #
+    # Example:
+    #   model: :electric_guitar  -> { ElectricGuitar }
+    def normalize_model_option
+      option_to_proc :model do |value|
+        model = case value
+        when String, Symbol then value.to_s.classify.constantize
+        else value
+        end
+
+        -> { model }
+      end
+    end
+
+    # Internal: Helper to normalize a non-proc value passed as an option.
+    def option_to_proc(name)
+      return unless option = options[name]
+      options[name] = yield(*option) unless option.is_a?(Proc)
+    end
+
+    # Internal: Asserts that the specified options are a Proc, if present.
+    def assert_proc_options(*names)
+      names.each do |name|
+        if options.key?(name) && !options[name].is_a?(Proc)
+          raise ArgumentError, "Can't handle #{name.inspect} => #{options[name].inspect} option"
+        end
+      end
+    end
+
+    # Internal: Performs a basic assertion to fail early if the specified
+    # options would result in undetermined behavior.
+    def assert_incompatible_options_pair(key1, key2)
+      if options.key?(key1) && options.key?(key2)
+        raise ArgumentError, "Using #{key1.inspect} option with #{key2.inspect} does not make sense"
+      end
+    end
+  end
+end

data/lib/resourcerer/controller.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Resourcerer
+  # Public: Provides two `resource` helper methods to simplify the definition
+  # and usage of Resources.
+  #
+  # It's also possible to define presets, which can then be reused by providing
+  # the :using option when using or defining a Resource.
+  module Controller
+    extend ActiveSupport::Concern
+
+    included do
+      # Public: Available configuration presets that can be used when defining
+      # a resource.
+      class_attribute :resourcerer_configuration,
+        instance_accessor: false, instance_predicate: false
+    end
+
+    def resource(*args)
+      Resource.new(self, *args).get(self)
+    end
+
+    module ClassMethods
+      # Public: Defines a Resource in a controller Class.
+      #
+      # *args - See Resource#initialize for details.
+      # block - If supplied, the block is executed to provide options.
+      #
+      # Returns the name of the defined resource.
+      def resource(*args, &block)
+        Resource.define(self, *args, &block)
+      end
+
+      # Public: Defines a Configuration preset that can be reused in different
+      # Resources by providing the :using option.
+      #
+      # name    - The Symbol name of the configuration preset.
+      # options - The Hash of options to define the preset.
+      # block   - If supplied, the block is executed to provide options.
+      #
+      # Returns a Hash with all the resource configurations.
+      def resourcerer_config(name, **options, &block)
+        self.resourcerer_configuration = (resourcerer_configuration || {}).merge(
+          name => Configuration.new(options, &block)
+        )
+      end
+    end
+  end
+end

data/lib/resourcerer/resource.rb

@@ -1,21 +1,206 @@
-require 'resourcerer/inflector'
-require 'resourcerer/strategies/strong_parameters_strategy'
+# frozen_string_literal: true
 
 module Resourcerer
+  # Public: Representation of a model that can be found, built, and assigned
+  # attributes.
   class Resource
-    attr_reader :name, :strategy, :options, :config_proc
+    attr_reader :name, :options, :controller
 
-    def self.for(name, options={}, config_proc=nil)
-      strategy_class = options.delete(:strategy) || Strategies::StrongParametersStrategy
-      new strategy_class, name, options, config_proc
+    # Public: Defines a Resource and makes it accessible to a controller.
+    # For each Resource, a getter and setter is defined in the controller.
+    #
+    # klass   - The Controller class where the Resource getter will be defined.
+    # name    - The name of the generated Resource.
+    # options - Config Hash for the new Resource. See Configuration::OPTIONS.
+    # block   - If supplied, the block is executed to provide options.
+    #
+    # Returns nothing.
+    def self.define(klass, name, **options, &block)
+      resource = new(klass, name, **options, &block)
+
+      klass.instance_eval do
+        ivar = "@resourcerer_#{ name.to_s.gsub('?', '_question_mark') }"
+
+        private define_method(name) {
+          if instance_variable_defined?(ivar)
+            instance_variable_get(ivar)
+          else
+            instance_variable_set(ivar, resource.clone.get(self))
+          end
+        }
+
+        private define_method("#{ name }=") { |value|
+          instance_variable_set(ivar, value)
+        }
+      end
+    end
+
+    # Public: Initalize a Resource with configuration options.
+    #
+    # klass       - The Controller class where the Resource is executed.
+    # name        - The Symbol name of the Resource instance.
+    # options     - Hash of options for the Configuration of the methods.
+    # block       - If supplied, the block is executed to provide options.
+    #
+    # Returns a normalized options Hash.
+    def initialize(klass, name, using: [], **options, &block)
+      @name = name
+      @options = Configuration.new(options, &block).options
+
+      Array.wrap(using).each do |preset|
+        klass.resourcerer_configuration.fetch(preset).apply(options)
+      end
+    end
+
+    # Public: Returns an object using the specified Resource configuration.
+    # The object will be built or found, and might be assigned attributes.
+    #
+    # controller - The instance of the controller where the resource is fetched.
+    #
+    # Returns the resource object.
+    def get(controller)
+      @controller = controller
+      collection = call(:collection, call(:model))
+
+      if id = call(:id)
+        call(:find, id, collection)
+      else
+        call(:build, safe_attrs, collection)
+      end.tap do |object|
+        call(:assign, object, safe_attrs) if object && call(:assign?, object)
+      end
+    end
+
+  protected
+
+    # Strategy: A query or table. Designed to be overridden.
+    #
+    # model - The Class to be scoped or queried.
+    #
+    # Returns the object collection.
+    def collection(model = name.to_s.classify.constantize)
+      model
+    end
+
+    # Strategy: Converts a name into a standard Class name.
+    #
+    # Examples
+    #   'egg_and_hams'.model # => EggAndHam
+    #
+    # Returns a standard Class name.
+    def model
+      options.key?(:collection) ? call(:collection).klass : collection
+    end
+
+    # Strategy: Checks controller params to retrieve an id value.
+    #
+    # Returns the id parameter, if any, or nil.
+    def id
+      ["#{name}_id", "#{model_name}_id", 'id'].uniq.
+        map { |id| controller.params[id] }.find(&:present?)
+    end
+
+    # Strategy: Find an object on the supplied scope.
+    #
+    # id    - The Integer id attribute of the desired object
+    # scope - The collection that will be searched.
+    #
+    # Returns the found object.
+    def find(id, collection)
+      collection.find(id)
+    end
+
+    # Strategy: Builds a new object on the passed-in scope.
+    #
+    # params - A Hash of attributes for the object to-be built.
+    # scope  - The collection where the object will be built from.
+    #
+    # Returns the new object.
+    def build(attrs, collection)
+      collection.new(attrs)
+    end
+
+    # Strategy: Assigns attributes to the found or built object.
+    #
+    # attrs  - A Hash of attributes to be assigned.
+    # object - The Resource object.
+    #
+    # Returns nothing.
+    def assign(object, attrs)
+      object.assign_attributes(attrs)
     end
 
-    def initialize(strategy, name, options, config_proc=nil)
-      @strategy, @name, @options, @config_proc = strategy, name, options, config_proc
+    # Strategy: Whether the attributes should be assigned.
+    #
+    # object - The Resource object.
+    #
+    # Returns true if attributes should be assigned, or false otherwise.
+    def assign?(object)
+      controller.action_name == 'update'
     end
 
-    def call(controller)
-      strategy.new(controller, name, options, config_proc).resource
+    # Strategy: Get all the parameters of the current request.
+    #
+    # Returns the controller's parameters for the current request.
+    def attrs
+      if options[:permit]
+        controller.params.require(model_name).permit(*call(:permit))
+      else
+        params_method = "#{name}_params"
+        if controller.respond_to?(params_method, true)
+          controller.send(params_method)
+        else
+          {}
+        end
+      end
+    end
+
+  private
+
+    # Internal: Avoids assigning attributes when the request is a GET request.
+    #
+    # Returns the controller's parameters for the current request.
+    def safe_attrs
+      controller.request.get? ? {} : call(:attrs)
+    end
+
+    # Internal: Returns a Symbol name that follows the parameter convention.
+    def model_name
+      @model_name ||= if defined?(ActiveModel::Name)
+        ActiveModel::Name.new(call(:model)).param_key
+      else
+        call(:model).name.underscore
+      end.to_sym
+    end
+
+    # Internal: Invokes a Proc that was passed as an option, or the default
+    # strategy for that function.
+    def call(name, *args)
+      memoize(name) {
+        if options.key?(name)
+          execute_option_function(options[name], *args)
+        else
+          send(name, *args)
+        end
+      }
+    end
+
+    # Internal: Invokes a Proc that was passed as an option. The Proc executes
+    # within the context of the controller.
+    def execute_option_function(function, *args)
+      args = args.first(function.parameters.length)
+      controller.instance_exec(*args, &function)
+    end
+
+    # Internal: Helper method to perform simple memoization.
+    def memoize(name)
+      ivar = "@#{ name.to_s.gsub('?', '_question_mark') }"
+
+      if instance_variable_defined?(ivar)
+        instance_variable_get(ivar)
+      else
+        instance_variable_set(ivar, yield)
+      end
     end
   end
 end