active_interaction 0.1.1

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# 0.1.1
+
+- Correct gemspec dependencies on activemodel.
+
+# 0.1.0
+
+- Initial release.

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Aaron Lasseigne
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,202 @@
+# ActiveInteraction
+
+[![Gem Version][]](https://badge.fury.io/rb/active_interaction)
+[![Build Status][]](https://travis-ci.org/orgsync/active_interaction)
+[![Coverage Status][]](https://coveralls.io/r/orgsync/active_interaction)
+[![Code Climate][]](https://codeclimate.com/github/orgsync/active_interaction)
+[![Dependency Status][]](https://gemnasium.com/orgsync/active_interaction)
+
+At first it seemed alright. A little business logic in a controller or model
+wasn't going to hurt anything. Then one day you wake up and you're surrounded
+by fat models and unweildy controllers. Curled up and crying in the
+corner, you can't help but wonder how it came to this.
+
+Take back control. Slim down models and wrangle monstrous controller methods
+with ActiveInteraction.
+
+## Installation
+
+This project uses [semantic versioning][].
+
+Add it to your Gemfile:
+
+~~~ rb
+gem 'active_interaction', '~> 0.1.1'
+~~~
+
+And then execute:
+
+~~~ sh
+$ bundle
+~~~
+
+Or install it yourself as:
+
+~~~ rb
+$ gem install active_interaction
+~~~
+
+## What do I get?
+
+ActiveInteraction::Base lets you create interaction models. These models ensure
+that certain options are provided and that those options are in the format you
+want them in. If the options are valid it will call `execute`, store the return
+value of that method in `result`, and return an instance of your ActiveInteraction::Base
+subclass. Let's looks at a simple example:
+
+~~~ rb
+# Define an interaction that signs up a user.
+class UserSignup < ActiveInteraction::Base
+  # required
+  string :email, :name
+
+  # optional
+  boolean :newsletter_subscribe, allow_nil: true
+
+  # ActiveRecord validations
+  validates :email, format: EMAIL_REGEX
+
+  # The execute method is called only if the options validate. It does your
+  # business action. The return value will be stored in `result`.
+  def execute
+    user = User.create!(email: email, name: name)
+    NewsletterSubscriptions.create(email: email, user_id: user.id) if newsletter_subscribe
+    UserMailer.async(:deliver_welcome, user.id)
+    user
+  end
+end
+
+# In a controller action (for instance), you can run it:
+def new
+  @signup = UserSignup.new
+end
+
+def create
+  @signup = UserSignup.run(params[:user])
+
+  # Then check to see if it worked:
+  if @signup.valid?
+    redirect_to welcome_path(user_id: signup.result.id)
+  else
+    render action: :new
+  end
+end
+~~~
+
+You may have noticed that ActiveInteraction::Base quacks like ActiveRecord::Base.
+It can use validations from your Rails application and check option validity with
+`valid?`. Any errors are added to `errors` which works exactly like an ActiveRecord
+model.
+
+## How do I call an interaction?
+
+There are two way to call an interaction. Given UserSignup, you can do this:
+
+~~~ rb
+outcome = UserSignup.run(params)
+if outcome.valid?
+  # Do something with outcome.result...
+else
+  # Do something with outcome.errors...
+end
+~~~
+
+Or, you can do this:
+
+~~~ rb
+result = UserSignup.run!(params)
+# Either returns the result of execute,
+# or raises ActiveInteraction::InteractionInvalid
+~~~
+
+## What can I pass to an interaction?
+
+Interactions only accept a Hash for `run` and `run!`.
+
+~~~ rb
+# A user comments on an article
+class CreateComment < ActiveInteraction::Base
+  model :article, :user
+  string :comment
+
+  validates :comment, length: {maximum: 500}
+
+  def execute; ...; end
+end
+
+def somewhere
+  outcome = CreateComment.run(
+    comment: params[:comment],
+    article: Article.find(params[:article_id]),
+    user: current_user
+  )
+end
+~~~
+
+## How do I define an interaction?
+
+1. Subclass ActiveInteraction::Base
+
+    ~~~ rb
+    class YourInteraction < ActiveInteraction::Base
+      # ...
+    end
+    ~~~
+
+2. Define your attributes:
+
+    ~~~ rb
+    string :name, :state
+    integer :age
+    boolean :is_special
+    model :account
+    array :tags, allow_nil: true do
+      string
+    end
+    hash :prefs, allow_nil: true do
+      boolean :smoking
+      boolean :view
+    end
+    date :arrives_on, default: Date.today
+    date :departs_on, default: Date.tomorrow
+    ~~~
+
+3. Use any additional validations you need:
+
+    ~~~ rb
+    validates :name, length: {maximum: 10}
+    validates :state, inclusion: {in: %w(AL AK AR ... WY)}
+    validate arrives_before_departs
+
+    private
+
+    def arrive_before_departs
+      if departs_on <= arrives_on
+        errors.add(:departs_on, 'must come after the arrival time')
+      end
+    end
+    ~~~
+
+4. Define your execute method. It can return whatever you like:
+
+    ~~~ rb
+    def execute
+      record = do_thing(...)
+      # ...
+      record
+    end
+    ~~~
+
+A full list of methods can be found [here](http://www.rubydoc.info/github/orgsync/active_interaction/master/ActiveInteraction/Base).
+
+## Credits
+
+This project was inspired by the fantastic work done in [Mutations][].
+
+[build status]: https://travis-ci.org/orgsync/active_interaction.png
+[code climate]: https://codeclimate.com/github/orgsync/active_interaction.png
+[coverage status]: https://coveralls.io/repos/orgsync/active_interaction/badge.png
+[dependency status]: https://gemnasium.com/orgsync/active_interaction.png
+[gem version]: https://badge.fury.io/rb/active_interaction.png
+[mutations]: https://github.com/cypriss/mutations
+[semantic versioning]: http://semver.org

data/lib/active_interaction.rb

@@ -0,0 +1,23 @@
+require 'active_model'
+
+require 'active_interaction/version'
+require 'active_interaction/errors'
+require 'active_interaction/overload_hash'
+require 'active_interaction/filter'
+require 'active_interaction/filter_method'
+require 'active_interaction/filter_methods'
+require 'active_interaction/filters/array_filter'
+require 'active_interaction/filters/boolean_filter'
+require 'active_interaction/filters/date_filter'
+require 'active_interaction/filters/date_time_filter'
+require 'active_interaction/filters/file_filter'
+require 'active_interaction/filters/float_filter'
+require 'active_interaction/filters/hash_filter'
+require 'active_interaction/filters/integer_filter'
+require 'active_interaction/filters/model_filter'
+require 'active_interaction/filters/string_filter'
+require 'active_interaction/filters/time_filter'
+require 'active_interaction/base'
+
+# @since 0.1.0
+module ActiveInteraction; end

data/lib/active_interaction/base.rb

@@ -0,0 +1,162 @@
+require 'active_support/core_ext/hash/indifferent_access'
+
+module ActiveInteraction
+  # @abstract Subclass and override {#execute} to implement
+  #   a custom ActiveInteraction class.
+  #
+  # @example
+  #   class ExampleInteraction < ActiveInteraction::Base
+  #     # Required
+  #     integer :a, :b
+  #
+  #     # Optional
+  #     integer :c, allow_nil: true
+  #
+  #     def execute
+  #       sum = a + b
+  #       c.nil? ? sum : sum + c
+  #     end
+  #   end
+  #
+  #   outcome = ExampleInteraction.run(a: 1, b: 2, c: 3)
+  #   if outcome.valid?
+  #     p outcome.result
+  #   else
+  #     p outcome.errors
+  #   end
+  class Base
+    extend  ::ActiveModel::Naming
+    include ::ActiveModel::Conversion
+    include ::ActiveModel::Validations
+
+    # @private
+    def new_record?
+      true
+    end
+
+    # @private
+    def persisted?
+      false
+    end
+
+    extend OverloadHash
+
+    # Returns the output from {#execute} if there are no validation errors or
+    #   `nil` otherwise.
+    #
+    # @return [Nil] if there are validation errors.
+    # @return [Object] if there are no validation errors.
+    attr_reader :result
+
+    # @private
+    def initialize(options = {})
+      options = options.with_indifferent_access
+
+      if options.has_key?(:result)
+        raise ArgumentError, ':result is reserved and can not be used'
+      end
+
+      options.each do |attribute, value|
+        if respond_to?("#{attribute}=")
+          send("#{attribute}=", value)
+        else
+          instance_variable_set("@#{attribute}", value)
+        end
+      end
+    end
+
+    # Runs the business logic associated with the interactor. The method is only
+    #   run when there are no validation errors. The return value is placed into
+    #   {#result}. This method must be overridden in the subclass.
+    #
+    # @raise [NotImplementedError] if the method is not defined.
+    def execute
+      raise NotImplementedError
+    end
+
+    # @!macro [new] run_attributes
+    #   @param options [Hash] Attribute values to set.
+
+    # Runs validations and if there are no errors it will call {#execute}.
+    #
+    # @macro run_attributes
+    #
+    # @return [ActiveInteraction::Base] An instance of the class `run` is called on.
+    def self.run(options = {})
+      me = new(options)
+
+      me.instance_variable_set(:@result, me.execute) if me.valid?
+
+      me
+    end
+
+    # Like {.run} except that it returns the value of {#execute} or raises an
+    #   exception if there were any validation errors.
+    #
+    # @macro run_attributes
+    #
+    # @raise [InteractionInvalid] if there are any errors on the model.
+    #
+    # @return The return value of {#execute}.
+    def self.run!(options = {})
+      outcome = run(options)
+      raise InteractionInvalid if outcome.invalid?
+      outcome.result
+    end
+
+    # @private
+    def self.method_missing(filter_type, *args, &block)
+      klass = Filter.factory(filter_type)
+      options = args.last.is_a?(Hash) ? args.pop : {}
+      args.each do |attribute|
+        filter_attr_accessor(klass, attribute, options, &block)
+
+        filter_validator(attribute, filter_type, klass, options, &block)
+      end
+    end
+    private_class_method :method_missing
+
+    # @private
+    def self.filter_attr_accessor(filter, attribute, options, &block)
+      attr_writer attribute
+
+      if options.has_key?(:default)
+        begin
+          default_value = filter.prepare(attribute, options.delete(:default), options, &block)
+        rescue InvalidValue
+          raise InvalidDefaultValue
+        end
+      end
+
+      define_method(attribute) do
+        instance_variable_name = "@#{attribute}"
+        if instance_variable_defined?(instance_variable_name)
+          instance_variable_get(instance_variable_name)
+        else
+          default_value
+        end
+      end
+    end
+    private_class_method :filter_attr_accessor
+
+    # @private
+    def self.filter_validator(attribute, type, filter, options, &block)
+      validator = "_validate__#{attribute}__#{type}"
+
+      validate validator
+
+      define_method(validator) do
+        begin
+          filter.prepare(attribute, send(attribute), options, &block)
+        rescue MissingValue
+          errors.add(attribute, 'is required')
+        rescue InvalidValue
+          errors.add(attribute,
+            "is not a valid #{type.to_s.humanize.downcase}")
+        end
+      end
+      private validator
+    end
+    private_class_method :filter_validator
+  end
+end

data/lib/active_interaction/errors.rb

@@ -0,0 +1,6 @@
+module ActiveInteraction
+  class InteractionInvalid < ::StandardError; end
+  class InvalidDefaultValue < ::StandardError; end
+  class InvalidValue < ::StandardError; end
+  class MissingValue < ::StandardError; end
+end

data/lib/active_interaction/filter.rb

@@ -0,0 +1,41 @@
+module ActiveInteraction
+  # @!macro [new] attribute_method_params
+  #   @param *attributes [Symbol] One or more attributes to create.
+  #   @param options [Hash]
+  #   @option options [Boolean] :allow_nil Allow a `nil` value.
+  #   @option options [Object] :default Value to use if `nil` is given.
+
+  # @private
+  class Filter
+    def self.factory(type)
+      klass = "#{type.to_s.camelize}Filter"
+
+      raise NoMethodError unless ActiveInteraction.const_defined?(klass)
+
+      ActiveInteraction.const_get(klass)
+    end
+
+    def self.prepare(key, value, options = {}, &block)
+      case value
+        when NilClass
+          return_nil(options[:allow_nil])
+        else
+          bad_value
+        end
+    end
+
+    def self.return_nil(allow_nil)
+      if allow_nil
+        nil
+      else
+        raise MissingValue
+      end
+    end
+    private_class_method :return_nil
+
+    def self.bad_value
+      raise InvalidValue
+    end
+    private_class_method :bad_value
+  end
+end