decent_exposure 2.3.3 → 3.0.0.beta1

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new
+
+task default: :spec

data/decent_exposure.gemspec

@@ -0,0 +1,30 @@
+require File.expand_path("../lib/decent_exposure/version", __FILE__)
+
+Gem::Specification.new do |spec|
+  spec.name         = "decent_exposure"
+  spec.version      = DecentExposure::VERSION
+  spec.authors      = ["Pavel Pravosud", "Stephen Caudill"]
+  spec.email        = ["info@hashrocket.com"]
+  spec.summary      = "A helper for creating declarative interfaces in controllers"
+  spec.description = %q{
+    DecentExposure helps you program to an interface, rather than an
+    implementation in your Rails controllers.  The fact of the matter is that
+    sharing state via instance variables in controllers promotes close coupling
+    with views.  DecentExposure gives you a declarative manner of exposing an
+    interface to the state that controllers contain and thereby decreasing
+    coupling and improving your testability and overall design.
+  }
+  spec.homepage     = "https://github.com/hashrocket/decent_exposure"
+  spec.license      = "MIT"
+  spec.files        = `git ls-files -z`.split("\x0")
+  spec.test_files   = spec.files.grep(/\Aspec\//)
+  spec.require_path = "lib"
+
+  spec.required_ruby_version = "~> 2.0"
+
+  spec.add_dependency "railties",      "~> 5.x"
+  spec.add_dependency "activesupport", "~> 5.x"
+  spec.add_development_dependency "rspec-rails", "~> 3.0"
+  spec.add_development_dependency "rake", "~> 10.3"
+  spec.add_development_dependency "pry"
+end

data/lib/decent_exposure.rb

@@ -1,6 +1,15 @@
-require 'decent_exposure/expose'
-require 'decent_exposure/error'
+require "decent_exposure/version"
+require "active_support/all"
 
-ActiveSupport.on_load(:action_controller) do
-  extend DecentExposure::Expose
+module DecentExposure
+  autoload :Controller, "decent_exposure/controller"
+  autoload :Exposure,   "decent_exposure/exposure"
+  autoload :Attribute,  "decent_exposure/attribute"
+  autoload :Context,    "decent_exposure/context"
+  autoload :Behavior,   "decent_exposure/behavior"
+  autoload :Flow,       "decent_exposure/flow"
+
+  ActiveSupport.on_load :action_controller do
+    include Controller
+  end
 end

data/lib/decent_exposure/attribute.rb

@@ -0,0 +1,55 @@
+module DecentExposure
+  class Attribute
+    attr_reader :name, :fetch, :ivar_name
+
+    # Public: Initialize an Attribute
+    #
+    # options - Hash of options for the Attribute
+    #           :name      - The String name of the Attribute instance
+    #           :fetch     - The Proc fetch to calculate
+    #                        the value of the Attribute instance.
+    #                        This is only called if the attribute's
+    #                        instance variable is not defined.
+    #           :ivar_name - The String instance variable name that
+    #                        is associated with the attribute.
+    def initialize(options)
+      @name = options.fetch(:name)
+      @fetch = options.fetch(:fetch)
+      @ivar_name = options.fetch(:ivar_name)
+    end
+
+    # Public: The getter method for the Attribute.
+    #
+    # Returns the name of the Attribute as a Symbol.
+    def getter_method_name
+      name.to_sym
+    end
+
+    # Public: The setter method for the Attribute.
+    #
+    # Returns the name of the attribute as a Symbol with an appended '='.
+    def setter_method_name
+      "#{name}=".to_sym
+    end
+
+
+    # Public: Expose a getter and setter method for the Attribute
+    # on the passed in Controller class.
+    #
+    # klass - The Controller class where the Attribute getter and setter
+    # methods will be exposed.
+    def expose!(klass)
+      attribute = self
+
+      klass.instance_eval do
+        define_method attribute.getter_method_name do
+          Context.new(self, attribute).get
+        end
+
+        define_method attribute.setter_method_name do |value|
+          Context.new(self, attribute).set(value)
+        end
+      end
+    end
+  end
+end

data/lib/decent_exposure/behavior.rb

@@ -0,0 +1,100 @@
+module DecentExposure
+  module Behavior
+    # Public: Fetches a scope.
+    #
+    # Finds an object. If it isn't found, the object gets instantiated.
+    #
+    # Returns the decorated object.
+    def fetch
+      instance = id ? find(id, computed_scope) : build(build_params, computed_scope)
+      decorate(instance)
+    end
+
+    # Public: Checks a params hash for an id attribute.
+    #
+    # Checks a hash of parameters for keys that represent an object's id.
+    #
+    # Returns the value of the id parameter, if it exists. Otherwise nil.
+    def id
+      params_id_key_candidates.each do |key|
+        value = params[key]
+        return value if value.present?
+      end
+
+      nil
+    end
+
+    # Public: An object query. Essentially, this method is designed to be
+    # overridden.
+    #
+    # model - The Class to be scoped or queried.
+    #
+    # Returns the object scope.
+    def scope(model)
+      model
+    end
+
+    # Public: Converts a name into a standard Class name.
+    #
+    # Examples
+    #   'egg_and_hams'.model # => EggAndHam
+    #
+    # Returns a standard Class name.
+    def model
+      name.to_s.classify.constantize
+    end
+
+    # Public: 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, scope)
+      scope.find(id)
+    end
+
+    # Public: Builds a new object on the passed-in scope.
+    #
+    # params - A Hash of attributes for the object to-be built.
+    # scope  - The collection that will be searched.
+    #
+    # Returns the new object.
+    def build(params, scope)
+      scope.new(params)
+    end
+
+    # Public: Returns a decorated object. This method is designed to be
+    # overridden.
+    #
+    # Returns the decorated object.
+    def decorate(instance)
+      instance
+    end
+
+    # Public: Get all the parameters of the current request.
+    #
+    # Returns the controller's parameters for the current request.
+    def build_params
+      if controller.respond_to?(params_method_name, true) && !get_request?
+        controller.send(params_method_name)
+      else
+        {}
+      end
+    end
+
+    protected
+
+    def params_id_key_candidates
+      [ "#{model_param_key}_id", "#{name}_id", "id" ].uniq
+    end
+
+    def model_param_key
+      model.name.underscore
+    end
+
+    def computed_scope
+      scope(model)
+    end
+  end
+end

data/lib/decent_exposure/context.rb

@@ -0,0 +1,61 @@
+module DecentExposure
+  class Context
+    attr_reader :context, :attribute
+
+    # Public: Initialize a context.
+    #
+    # context   - The Class where the attribute is defined.
+    # attribute - The attribute that will be accessed by a getter
+    #             and setter.
+    def initialize(context, attribute)
+      @context, @attribute = context, attribute
+    end
+
+    # Public: Read an attribute on the context Class.
+    #
+    # Get an attribute's value. If the attribute's instance
+    # variable is not defined, it will create one,
+    # execute attribute#fetch, and assign the result
+    # to the instance variable.
+    #
+    # Returns the attribute's value.
+    def get
+      ivar_defined?? ivar_get : set(fetch_value)
+    end
+
+    # Public: Write to an attribute on the context Class.
+    #
+    # value - The value that will be set to the attribute's
+    #         instance variable.
+    #
+    # Returns the attribute's value.
+    def set(value)
+      ivar_set(value)
+    end
+
+    private
+
+    delegate :instance_variable_set, :instance_variable_get,
+      :instance_variable_defined?, to: :context
+
+    def ivar_defined?
+      instance_variable_defined?(ivar_name)
+    end
+
+    def ivar_get
+      instance_variable_get(ivar_name)
+    end
+
+    def ivar_set(value)
+      instance_variable_set(ivar_name, value)
+    end
+
+    def ivar_name
+      "@#{attribute.ivar_name}"
+    end
+
+    def fetch_value
+      context.instance_exec(&attribute.fetch)
+    end
+  end
+end

data/lib/decent_exposure/controller.rb

@@ -0,0 +1,53 @@
+module DecentExposure
+  module Controller
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :exposure_configuration,
+        instance_accessor: false, instance_predicate: false
+    end
+
+    module ClassMethods
+      # Public: Exposes an attribute to a controller Class.
+      #
+      # *args - An Array of attributes for the new exposure. See
+      #         Exposure#initialize for attribute details.
+      # block - If supplied, the exposed attribute method executes
+      #         the Proc when accessed.
+      #
+      # Returns the helper methods that are now defined on the class
+      # where this method is included.
+      def expose(*args, &block)
+        Exposure.expose! self, *args, &block
+      end
+
+      # Public: Exposes an attribute to a controller Class.
+      # The exposed methods are then set to a before_action
+      # callback.
+      #
+      # name  - The String name of the Exposure instance.
+      # *args - An Array of attributes for the new exposure. See
+      #         Exposure#initialize for attribute details.
+      # block - If supplied, the exposed attribute method executes
+      #         the Proc when accessed.
+      #
+      # Sets the exposed attribute to a before_action callback in the
+      # controller.
+      def expose!(name, *args, &block)
+        expose name, *args, &block
+        before_action name
+      end
+
+      # Public: Configures an Exposure instance for a controller Class.
+      #
+      # name    - The String name of the Exposure instance.
+      # options - The Hash of options to configure the Exposure instance.
+      #
+      # Returns the exposure configuration Hash.
+      def exposure_config(name, options)
+        store = self.exposure_configuration ||= {}
+        self.exposure_configuration = store.merge(name => options)
+      end
+    end
+  end
+end

data/lib/decent_exposure/exposure.rb

@@ -1,17 +1,207 @@
-require 'decent_exposure/inflector'
-
 module DecentExposure
   class Exposure
-    attr_accessor :name, :strategy, :options
+    attr_reader :controller, :options
+
+    # Public: Initializes an Exposure and makes it accessible to a controller.
+    # For each Exposure, a getter and setter is defined.
+    # Those getters and setters are made available to
+    # the controller as helper methods.
+    #
+    # *args  - An Array of all parameters for the new Exposure. See
+    #          #initialize.
+    # block  - If supplied, the exposed attribute method executes
+    #          the Proc when called.
+    #
+    # Returns a collection of exposed helper methods.
+    def self.expose!(*args, &block)
+      new(*args, &block).expose!
+    end
+
+    # Public: Initalize an Exposure with a hash of options.
+    #
+    # If a block is given, the Proc is assigned to value
+    # of options[name].
+    #
+    # The `asserts_*` section raise errors if the controller
+    # was initialized with an unacceptable options Hash.
+    #
+    # controller  - The Controller class where methods will be exposed.
+    # name        - The String name of the Exposure instance.
+    # fetch_block - Proc that will be executed if the exposed
+    #               attribute has no value (default: nil).
+    # options     - Hash of options for the Behavior of the exposed methods.
+    # block       - If supplied, the exposed attribute method executes
+    #               the Proc.
+    #
+    # Returns a normalized options Hash.
+    def initialize(controller, name, fetch_block=nil, **options, &block)
+      @controller = controller
+      @options = options.with_indifferent_access.merge(name: name)
+
+      merge_lambda_option :fetch, fetch_block if fetch_block
+      merge_lambda_option :fetch, block if block_given?
+
+      assert_singleton_option :fetch
+      assert_singleton_option :from
+      assert_incompatible_options_pair :parent, :model
+      assert_incompatible_options_pair :parent, :scope
+      assert_incompatible_options_pair :find_by, :find
+
+      normalize_options
+    end
+
+    # Public: Creates a getter and setter methods for the attribute.
+    # Those methods are made avaiable to the controller as
+    # helper methods.
+    #
+    # Returns a collection of exposed helper methods.
+    def expose!
+      expose_attribute!
+      expose_helper_methods!
+    end
+
+    private
+
+    def expose_attribute!
+      attribute.expose! controller
+    end
+
+    def expose_helper_methods!
+      helper_methods = [ attribute.getter_method_name, attribute.setter_method_name ]
+      controller.helper_method *helper_methods
+    end
+
+    def normalize_options
+      normalize_fetch_option
+      normalize_with_option
+      normalize_id_option
+      normalize_model_option
+      normalize_build_params_option
+      normalize_scope_options
+      normalize_parent_option
+      normalize_from_option
+      normalize_find_by_option
+    end
+
+    def normalize_fetch_option
+      normalize_non_proc_option :fetch do |method_name|
+        ->{ send(method_name) }
+      end
+    end
+
+    def normalize_find_by_option
+      if find_by = options.delete(:find_by)
+        merge_lambda_option :find, ->(id, scope){ scope.find_by!(find_by => id) }
+      end
+    end
+
+    def normalize_parent_option
+      exposure_name = options.fetch(:name)
+
+      if parent = options.delete(:parent)
+        merge_lambda_option :scope, ->{ send(parent).send(exposure_name.to_s.pluralize) }
+      end
+    end
+
+    def normalize_from_option
+      exposure_name = options.fetch(:name)
+
+      if from = options.delete(:from)
+        merge_lambda_option :build, ->{ send(from).send(exposure_name) }
+        merge_lambda_option :model, ->{ nil }
+        merge_lambda_option :id, ->{ nil }
+      end
+    end
+
+    def normalize_with_option
+      if configs = options.delete(:with)
+        Array.wrap(configs).each{ |config| reverse_merge_config! config }
+      end
+    end
+
+    def normalize_id_option
+      normalize_non_proc_option :id do |ids|
+        ->{ Array.wrap(ids).map{ |id| params[id] }.find(&:present?) }
+      end
+    end
+
+    def normalize_model_option
+      normalize_non_proc_option :model do |value|
+        model = if [String, Symbol].include?(value.class)
+          value.to_s.classify.constantize
+        else
+          value
+        end
+
+        ->{ model }
+      end
+    end
+
+    def normalize_build_params_option
+      normalize_non_proc_option :build_params do |value|
+        options[:build_params_method] = value
+        nil
+      end
+    end
+
+    def normalize_scope_options
+      normalize_non_proc_option :scope do |custom_scope|
+        ->(model){ model.send(custom_scope) }
+      end
+    end
+
+    def normalize_non_proc_option(name)
+      option_value = options[name]
+      return if Proc === option_value
+      if option_value.present?
+        normalized_value = yield(option_value)
+        if normalized_value
+          merge_lambda_option name, normalized_value
+        else
+          options.delete name
+        end
+      end
+    end
+
+    def merge_lambda_option(name, body)
+      if previous_value = options[name] and Proc === previous_value
+        fail ArgumentError, "#{name.to_s.titleize} block is already defined"
+      end
+
+      options[name] = body
+    end
+
+    def attribute
+      @attribute ||= begin
+        local_options = options
+
+        name = options.fetch(:name)
+        ivar_name = "exposed_#{name}"
+        fetch = ->{ Flow.new(self, local_options).fetch }
+
+        Attribute.new(
+          name: name,
+          ivar_name: ivar_name,
+          fetch: fetch
+        )
+      end
+    end
+
+    def assert_incompatible_options_pair(key1, key2)
+      if options.key?(key1) && options.key?(key2)
+        fail ArgumentError, "Using #{key1.inspect} option with #{key2.inspect} doesn't make sense"
+      end
+    end
 
-    def initialize(name, strategy, options)
-      self.name = name.to_s
-      self.strategy = strategy
-      self.options = options
+    def assert_singleton_option(name)
+      if options.except(name, :name, :decorate).any? && options.key?(name)
+        fail ArgumentError, "Using #{name.inspect} option with other options doesn't make sense"
+      end
     end
 
-    def call(controller)
-      strategy.new(controller, name, options).resource
+    def reverse_merge_config!(name)
+      config = controller.exposure_configuration.fetch(name)
+      options.reverse_merge! config
     end
   end
 end