active_interaction 0.10.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 88026615847767352e357dadf32abd0a6a114889
-  data.tar.gz: 5dd283e9aee1bab91a73ea20d52a7c8c24d5bed9
+  metadata.gz: 02f4ec454ba99aa3327ab6d539a8dd2f6e9b8622
+  data.tar.gz: e20fe1fb15d09040a7c00379962f53ac41d26cf1
 SHA512:
-  metadata.gz: 0d6082582172127078839165df075f8de2f222a3ed6822f52ad69270c6240e9d3f3eacfbfc95e3bd4989e21e43d371182b3ca1a09a9639ac14546d7c76b604d6
-  data.tar.gz: 6e81489a89de567be04f3f8713f88a0af5959de1fd2954b3731b1ce6ff7335615d423a59a428bd2081aa64a6a6dfede40e422005fbbb60cf3737f2a9e791ec31
+  metadata.gz: ab410e55639bb75899387091d50213f0b53b4d58de8b4cc0c3cc36d9c0f2acdc247bfe88662d276ed635a3fc695631a291c6c1f6234a7a46c38b4615127b3c7f
+  data.tar.gz: f48693acfcc32d503fdc03af08cad9b2ed1a4c7fb32b7dac467f30e325ab97f3647c7b79d865686d26a1cd93fb04ca9b449e52a8d247086a3bd1cb27ab85aad2

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # [Master][]
 
+# [1.0.0][]
+
+- **Replace `Filters` with a hash.** To iterate over `Filter` objects, use
+  `Interaction.filters.values`.
+- Rename `Filter#has_default?` to `Filter#default?`.
+- Add `respond_to_missing?` to complement `method_missing` calls.
+- Add predicate methods for checking if an input was passed.
+- When adding a filter that shares a name with an existing filter, it will now
+  replace the existing one instead of adding a duplicate.
+- Allow fetching filters by name.
+- Allow import filters from another interaction with `import_filters`.
+
 # [0.10.2][] (2014-01-02)
 
 - Fix a bug that marked Time instances as invalid if Time.zone was set.
@@ -106,7 +118,8 @@
 
 - Initial release.
 
-  [master]: https://github.com/orgsync/active_interaction/compare/v0.10.2...master
+  [master]: https://github.com/orgsync/active_interaction/compare/v1.0.0...master
+  [1.0.0]: https://github.com/orgsync/active_interaction/compare/v0.10.2...v1.0.0
   [0.10.2]: https://github.com/orgsync/active_interaction/compare/v0.10.1...v0.10.2
   [0.10.1]: https://github.com/orgsync/active_interaction/compare/v0.10.0...v0.10.1
   [0.10.0]: https://github.com/orgsync/active_interaction/compare/v0.9.1...v0.10.0

data/README.md

@@ -1,10 +1,10 @@
-# ActiveInteraction
+# [ActiveInteraction][0]
 
-[![Gem Version][]][1]
-[![Build Status][]][2]
-[![Coverage Status][]][3]
-[![Code Climate][]][4]
-[![Dependency Status][]][5]
+[![Gem Version][1]][2]
+[![Build Status][3]][4]
+[![Coverage Status][5]][6]
+[![Code Climate][7]][8]
+[![Dependency Status][9]][10]
 
 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
@@ -15,17 +15,17 @@ to this.
 Take back control. Slim down models and wrangle monstrous controller
 methods with ActiveInteraction.
 
-Read more on the [project page][] or check out the full [documentation][]
+Read more on the [project page][11] or check out the full [documentation][12]
 on RubyDoc.info.
 
 ## Installation
 
-This project uses [semantic versioning][].
+This project uses [semantic versioning][13].
 
 Add it to your Gemfile:
 
 ```ruby
-gem 'active_interaction', '~> 0.10.2'
+gem 'active_interaction', '~> 1.0'
 ```
 
 And then execute:
@@ -198,12 +198,10 @@ end
     end
     ```
 
-Check out the [documentation][] for a full list of methods.
+Check out the [documentation][12] for a full list of methods.
 
 ## How do I compose interactions?
 
-(Note: this feature is experimental. See [#41][] & [#79][].)
-
 You can run interactions from within other interactions by calling `compose`.
 If the interaction is successful, it'll return the result (just like if you had
 called it with `run!`). If something went wrong, execution will halt
@@ -278,26 +276,25 @@ p Interaction.run.errors.messages
 
 ## Credits
 
-ActiveInteraction is brought to you by [@AaronLasseigne][] and
-[@tfausak][] from [@orgsync][]. We were inspired by the fantastic
-work done in [Mutations][].
-
-  [#41]: https://github.com/orgsync/active_interaction/issues/41
-  [#79]: https://github.com/orgsync/active_interaction/issues/79
-  [1]: https://badge.fury.io/rb/active_interaction "Gem Version"
-  [2]: https://travis-ci.org/orgsync/active_interaction "Build Status"
-  [3]: https://coveralls.io/r/orgsync/active_interaction "Coverage Status"
-  [4]: https://codeclimate.com/github/orgsync/active_interaction "Code Climate"
-  [5]: https://gemnasium.com/orgsync/active_interaction "Dependency Status"
-  [@AaronLasseigne]: https://github.com/AaronLasseigne
-  [@orgsync]: https://github.com/orgsync
-  [@tfausak]: https://github.com/tfausak
-  [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
-  [documentation]: http://rubydoc.info/github/orgsync/active_interaction
-  [gem version]: https://badge.fury.io/rb/active_interaction.png
-  [mutations]: https://github.com/cypriss/mutations
-  [project page]: http://orgsync.github.io/active_interaction/
-  [semantic versioning]: http://semver.org/spec/v2.0.0.html
+ActiveInteraction is brought to you by [@AaronLasseigne][14] and
+[@tfausak][15] from [@orgsync][16]. We were inspired by the fantastic
+work done in [Mutations][17].
+
+  [0]: https://github.com/orgsync/active_interaction
+  [1]: https://badge.fury.io/rb/active_interaction.png
+  [2]: https://badge.fury.io/rb/active_interaction "Gem Version"
+  [3]: https://travis-ci.org/orgsync/active_interaction.png
+  [4]: https://travis-ci.org/orgsync/active_interaction "Build Status"
+  [5]: https://coveralls.io/repos/orgsync/active_interaction/badge.png
+  [6]: https://coveralls.io/r/orgsync/active_interaction "Coverage Status"
+  [7]: https://codeclimate.com/github/orgsync/active_interaction.png
+  [8]: https://codeclimate.com/github/orgsync/active_interaction "Code Climate"
+  [9]: https://gemnasium.com/orgsync/active_interaction.png
+  [10]: https://gemnasium.com/orgsync/active_interaction "Dependency Status"
+  [11]: http://orgsync.github.io/active_interaction/
+  [12]: http://rubydoc.info/github/orgsync/active_interaction
+  [13]: http://semver.org/spec/v2.0.0.html
+  [14]: https://github.com/AaronLasseigne
+  [15]: https://github.com/tfausak
+  [16]: https://github.com/orgsync
+  [17]: https://github.com/cypriss/mutations

data/lib/active_interaction.rb

@@ -5,14 +5,15 @@ require 'active_model'
 require 'active_interaction/version'
 require 'active_interaction/errors'
 
-require 'active_interaction/modules/active_model'
-require 'active_interaction/modules/core'
-require 'active_interaction/modules/method_missing'
-require 'active_interaction/modules/overload_hash'
+require 'active_interaction/concerns/active_modelable'
+require 'active_interaction/concerns/hashable'
+require 'active_interaction/concerns/missable'
+require 'active_interaction/concerns/runnable'
+
 require 'active_interaction/modules/validation'
 
 require 'active_interaction/filter'
-require 'active_interaction/filters'
+require 'active_interaction/filters/abstract_filter'
 require 'active_interaction/filters/abstract_date_time_filter'
 require 'active_interaction/filters/abstract_numeric_filter'
 require 'active_interaction/filters/array_filter'
@@ -34,5 +35,12 @@ I18n.backend.load_translations(
   Dir[File.join(%w(lib active_interaction locale *.yml))]
 )
 
-# @since 0.1.0
+# Manage application specific business logic.
+#
+# @author Aaron Lasseigne <aaron.lasseigne@gmail.com>
+# @author Taylor Fausak <taylor@fausak.me>
+#
+# @since 1.0.0
+#
+# @version 1.0.0
 module ActiveInteraction end

data/lib/active_interaction/base.rb

@@ -4,199 +4,219 @@ require 'active_support/core_ext/hash/indifferent_access'
 
 module ActiveInteraction
   # @abstract Subclass and override {#execute} to implement a custom
-  #   ActiveInteraction class.
+  #   ActiveInteraction::Base class.
+  #
+  # Provides interaction functionality. Subclass this to create an interaction.
   #
   # @example
   #   class ExampleInteraction < ActiveInteraction::Base
   #     # Required
-  #     integer :a, :b
+  #     boolean :a
   #
   #     # Optional
-  #     integer :c, default: nil
+  #     boolean :b, default: false
   #
   #     def execute
-  #       sum = a + b
-  #       c.nil? ? sum : sum + c
+  #       a && b
   #     end
   #   end
   #
-  #   outcome = ExampleInteraction.run(a: 1, b: 2, c: 3)
+  #   outcome = ExampleInteraction.run(a: true)
   #   if outcome.valid?
-  #     p outcome.result
+  #     outcome.result
   #   else
-  #     p outcome.errors
+  #     outcome.errors
   #   end
   class Base
-    include ActiveModel
+    include ActiveModelable
+    include Runnable
+
+    validate :input_errors
+
+    class << self
+      include Hashable
+      include Missable
+
+      # Get or set the description.
+      #
+      # @example
+      #   core.desc
+      #   # => nil
+      #   core.desc('Description!')
+      #   core.desc
+      #   # => "Description!"
+      #
+      # @param desc [String, nil] What to set the description to.
+      #
+      # @return [String, nil] The description.
+      def desc(desc = nil)
+        if desc.nil?
+          unless instance_variable_defined?(:@_interaction_desc)
+            @_interaction_desc = nil
+          end
+        else
+          @_interaction_desc = desc
+        end
 
-    extend Core
-    extend MethodMissing
-    extend OverloadHash
+        @_interaction_desc
+      end
 
-    validate :input_errors, :runtime_errors
+      # Get all the filters defined on this interaction.
+      #
+      # @return [Hash{Symbol => Filter}]
+      def filters
+        @_interaction_filters ||= {}
+      end
 
-    # @param inputs [Hash{Symbol => Object}] Attribute values to set.
-    #
-    # @private
-    def initialize(inputs = {})
-      fail ArgumentError, 'inputs must be a hash' unless inputs.is_a?(Hash)
+      # @private
+      def method_missing(*args, &block)
+        super do |klass, names, options|
+          fail InvalidFilterError, 'missing attribute name' if names.empty?
 
-      @_interaction_errors = Errors.new(self)
-      @_interaction_result = nil
-      @_interaction_runtime_errors = nil
+          names.each { |name| add_filter(klass, name, options, &block) }
+        end
+      end
 
-      process_inputs(inputs.symbolize_keys)
-    end
+      # @!method run(inputs = {})
+      #   Runs validations and if there are no errors it will call {#execute}.
+      #
+      #   @param (see ActiveInteraction::Base#initialize)
+      #
+      #   @return [Base]
+      loop
+
+      # @!method run!(inputs = {})
+      #   Like {.run} except that it returns the value of {#execute} or raises
+      #     an exception if there were any validation errors.
+      #
+      #   @param (see ActiveInteraction::Base.run)
+      #
+      #   @return (see ActiveInteraction::Runnable::ClassMethods#run!)
+      #
+      #   @raise (see ActiveInteraction::Runnable::ClassMethods#run!)
+      loop
+
+      private
+
+      # @param klass [Class]
+      # @param name [Symbol]
+      # @param options [Hash]
+      def add_filter(klass, name, options, &block)
+        fail InvalidFilterError, name.inspect if reserved?(name)
+
+        filter = klass.new(name, options, &block)
+        filters[name] = filter
+        attr_accessor name
+        define_method("#{name}?") { !public_send(name).nil? }
+
+        filter.default if filter.default?
+      end
 
-    # Returns the inputs provided to {.run} or {.run!} after being cast based
-    #   on the filters in the class.
-    #
-    # @return [Hash{Symbol => Object}] All inputs passed to {.run} or {.run!}.
-    #
-    # @since 0.6.0
-    def inputs
-      self.class.filters.each_with_object({}) do |filter, h|
-        h[filter.name] = send(filter.name)
+      # Import filters from another interaction.
+      #
+      # @param klass [Class] The other interaction.
+      # @param options [Hash]
+      #
+      # @option options [Array<Symbol>, nil] :only Import only these filters.
+      # @option options [Array<Symbol>, nil] :except Import all filters except
+      #   for these.
+      #
+      # @return (see .filters)
+      #
+      # @!visibility public
+      def import_filters(klass, options = {})
+        if options.key?(:only) && options.key?(:except)
+          fail ArgumentError, 'given both :only and :except'
+        end
+
+        only = options[:only]
+        except = options[:except]
+
+        other_filters = klass.filters.dup
+        other_filters.select! { |k, _| only.include?(k) } if only
+        other_filters.reject! { |k, _| except.include?(k) } if except
+
+        filters.merge!(other_filters)
       end
-    end
 
-    # Runs the business logic associated with the interaction. 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.
-    #   This method is run in a transaction if ActiveRecord is available.
-    #
-    # @raise [NotImplementedError] if the method is not defined.
-    #
-    # @abstract
-    def execute
-      fail NotImplementedError
-    end
+      # @param klass [Class]
+      def inherited(klass)
+        klass.instance_variable_set(:@_interaction_filters, filters.dup)
+      end
 
-    # Returns the output from {#execute} if there are no validation errors or
-    #   `nil` otherwise.
-    #
-    # @return [Object, nil] the output or nil if there were validation errors
-    def result
-      @_interaction_result
+      # @param symbol [Symbol]
+      #
+      # @return [Boolean]
+      def reserved?(symbol)
+        symbol.to_s.start_with?('_interaction_')
+      end
     end
 
+    # @param inputs [Hash{Symbol => Object}] Attribute values to set.
+    #
     # @private
-    def errors
-      @_interaction_errors
-    end
+    def initialize(inputs = {})
+      fail ArgumentError, 'inputs must be a hash' unless inputs.is_a?(Hash)
 
-    # @private
-    def valid?(*args)
-      super(*args) || (@_interaction_result = nil)
+      process_inputs(inputs.symbolize_keys)
     end
 
-    # Get all the filters defined on this interaction.
+    # @!method compose(other, inputs = {})
+    #   Run another interaction and return its result. If the other interaction
+    #     fails, halt execution.
     #
-    # @return [Filters]
+    #   @param other (see ActiveInteraction::Runnable#compose)
+    #   @param inputs (see ActiveInteraction::Base#initialize)
     #
-    # @since 0.6.0
-    def self.filters
-      @_interaction_filters ||= Filters.new
-    end
+    #   @return (see ActiveInteraction::Base.run!)
+    loop
 
-    # Runs validations and if there are no errors it will call {#execute}.
+    # @!method execute
+    #   @abstract
     #
-    # @param (see #initialize)
+    #   Runs the business logic associated with the interaction. This method is
+    #     only run when there are no validation errors. The return value is
+    #     placed into {#result}. This method is run in a transaction if
+    #     ActiveRecord is available.
     #
-    # @return [ActiveInteraction::Base] An instance of the class `run` is
-    #   called on.
-    def self.run(*args)
-      new(*args).tap do |interaction|
-        if interaction.valid?
-          result = transaction do
-            begin
-              interaction.execute
-            rescue Interrupt
-              # Inner interaction failed. #compose handles merging errors.
-            end
-          end
-
-          if interaction.errors.empty?
-            interaction.instance_variable_set(:@_interaction_result, result)
-          else
-            interaction.instance_variable_set(
-              :@_interaction_runtime_errors, interaction.errors.dup)
-          end
-        end
-      end
-    end
+    #   @raise (see ActiveInteraction::Runnable#execute)
+    loop
 
-    # @private
-    def self.method_missing(*args, &block)
-      super do |klass, names, options|
-        fail InvalidFilterError, 'missing attribute name' if names.empty?
-
-        names.each do |attribute|
-          if attribute.to_s.start_with?('_interaction_')
-            fail InvalidFilterError, attribute.inspect
-          end
-
-          filter = klass.new(attribute, options, &block)
-          filters.add(filter)
-          attr_accessor filter.name
-
-          # This isn't required, but it makes invalid defaults raise errors on
-          #   class definition instead of on execution.
-          filter.default if filter.has_default?
-        end
+    # Returns the inputs provided to {.run} or {.run!} after being cast based
+    #   on the filters in the class.
+    #
+    # @return [Hash{Symbol => Object}] All inputs passed to {.run} or {.run!}.
+    def inputs
+      self.class.filters.keys.each_with_object({}) do |name, h|
+        h[name] = public_send(name)
       end
     end
 
     private
 
+    # @param inputs [Hash{Symbol => Object}]
     def process_inputs(inputs)
       inputs.each do |key, value|
-        if key.to_s.start_with?('_interaction_')
-          fail InvalidValueError, key.inspect
-        end
+        fail InvalidValueError, key.inspect if self.class.send(:reserved?, key)
 
         instance_variable_set("@#{key}", value)
       end
 
-      self.class.filters.each do |filter|
+      self.class.filters.each do |name, filter|
         begin
-          send("#{filter.name}=", filter.clean(inputs[filter.name]))
+          public_send("#{name}=", filter.clean(inputs[name]))
         rescue InvalidValueError, MissingValueError
           # Validators (#input_errors) will add errors if appropriate.
         end
       end
     end
 
+    # @!group Validations
+
     def input_errors
       Validation.validate(self.class.filters, inputs).each do |error|
         errors.add_sym(*error)
       end
     end
-
-    def runtime_errors
-      if @_interaction_runtime_errors
-        errors.merge!(@_interaction_runtime_errors)
-      end
-    end
-
-    def compose(interaction, inputs = {})
-      outcome = interaction.run(inputs)
-      return outcome.result if outcome.valid?
-
-      # This can't use Errors#merge! because the errors have to be added to
-      # base.
-      outcome.errors.full_messages.each do |message|
-        errors.add(:base, message) unless errors.added?(:base, message)
-      end
-
-      fail Interrupt
-    end
-
-    def self.inherited(klass)
-      new_filters = Filters.new
-      filters.each { |f| new_filters.add(f) }
-
-      klass.instance_variable_set(:@_interaction_filters, new_filters)
-    end
   end
 end