active_interaction 0.10.2 → 1.0.0

data/lib/active_interaction/concerns/active_modelable.rb

@@ -0,0 +1,46 @@
+# coding: utf-8
+
+module ActiveInteraction
+  # Implement the minimal ActiveModel interface.
+  #
+  # @private
+  module ActiveModelable
+    extend ActiveSupport::Concern
+
+    include ActiveModel::Conversion
+    include ActiveModel::Validations
+
+    extend ActiveModel::Naming
+
+    # @return (see ClassMethods#i18n_scope)
+    #
+    # @see ActiveModel::Translation#i18n_scope
+    def i18n_scope
+      self.class.i18n_scope
+    end
+
+    # @return [Boolean]
+    #
+    # @see ActiveRecord::Presistence#new_record?
+    def new_record?
+      true
+    end
+
+    # @return [Boolean]
+    #
+    # @see ActiveRecord::Presistence#persisted?
+    def persisted?
+      false
+    end
+
+    #
+    module ClassMethods
+      # @return [Symbol]
+      #
+      # @see ActiveModel::Translation#i18n_scope
+      def i18n_scope
+        :active_interaction
+      end
+    end
+  end
+end

data/lib/active_interaction/{modules/overload_hash.rb → concerns/hashable.rb}

@@ -1,8 +1,12 @@
 # coding: utf-8
 
 module ActiveInteraction
+  # Allow `hash` to be overridden when given arguments and/or a block.
+  #
   # @private
-  module OverloadHash
+  module Hashable
+    extend ActiveSupport::Concern
+
     def hash(*args, &block)
       if args.empty? && !block_given?
         super

data/lib/active_interaction/concerns/missable.rb

@@ -0,0 +1,47 @@
+# coding: utf-8
+
+module ActiveInteraction
+  # Handle common `method_missing` functionality.
+  #
+  # @private
+  module Missable
+    extend ActiveSupport::Concern
+
+    # @param slug [Symbol]
+    #
+    # @yield [klass, args, options]
+    #
+    # @yieldparam klass [Class]
+    # @yieldparam args [Array]
+    # @yieldparam options [Hash]
+    #
+    # @return [Missable]
+    def method_missing(slug, *args, &block)
+      return super unless (klass = filter(slug))
+
+      options = args.last.is_a?(Hash) ? args.pop : {}
+
+      yield(klass, args, options) if block_given?
+
+      self
+    end
+
+    private
+
+    # @param slug [Symbol]
+    #
+    # @return [Filter, nil]
+    def filter(slug)
+      Filter.factory(slug)
+    rescue MissingFilterError
+      nil
+    end
+
+    # @param slug [Symbol]
+    #
+    # @return [Boolean]
+    def respond_to_missing?(slug, *)
+      !!filter(slug)
+    end
+  end
+end

data/lib/active_interaction/concerns/runnable.rb

@@ -0,0 +1,156 @@
+# coding: utf-8
+
+begin
+  require 'active_record'
+rescue LoadError
+  module ActiveRecord
+    #
+    class Base
+      def self.transaction(*)
+        yield
+      end
+    end
+  end
+end
+
+module ActiveInteraction
+  # @abstract Include and override {#execute} to implement a custom Runnable
+  #   class.
+  #
+  # @note Must be included after `ActiveModel::Validations`.
+  #
+  # Runs code in transactions and only provides the result if there are no
+  #   validation errors.
+  #
+  # @private
+  module Runnable
+    extend ActiveSupport::Concern
+    include ActiveModel::Validations
+
+    included do
+      validate :runtime_errors
+    end
+
+    # @return [Errors]
+    def errors
+      @_interaction_errors
+    end
+
+    # @abstract
+    #
+    # @raise [NotImplementedError]
+    def execute
+      fail NotImplementedError
+    end
+
+    # @return [Object] If there are no validation errors.
+    # @return [nil] If there are validation errors.
+    def result
+      @_interaction_result
+    end
+
+    # @param result [Object]
+    #
+    # @return (see #result)
+    def result=(result)
+      if errors.empty?
+        @_interaction_result = result
+        @_interaction_runtime_errors = nil
+      else
+        @_interaction_result = nil
+        @_interaction_runtime_errors = errors.dup
+      end
+    end
+
+    # @return [Boolean]
+    def valid?(*)
+      super || (self.result = nil)
+    end
+
+    private
+
+    # @param other [Class] The other interaction.
+    # @param (see ClassMethods.run)
+    #
+    # @return (see #result)
+    #
+    # @raise [Interrupt]
+    def compose(other, *args)
+      outcome = other.run(*args)
+
+      if outcome.valid?
+        outcome.result
+      else
+        fail Interrupt, outcome
+      end
+    end
+
+    # @return (see #result=)
+    # @return [nil]
+    def run
+      return unless valid?
+
+      self.result = ActiveRecord::Base.transaction do
+        begin
+          execute
+        rescue Interrupt => interrupt
+          interrupt.outcome.errors.full_messages.each do |message|
+            errors.add(:base, message) unless errors.added?(:base, message)
+          end
+        end
+      end
+    end
+
+    # @return [Object]
+    #
+    # @raise [InvalidInteractionError] If there are validation errors.
+    def run!
+      run
+
+      if valid?
+        result
+      else
+        fail InvalidInteractionError, errors.full_messages.join(', ')
+      end
+    end
+
+    # @!group Validations
+
+    def runtime_errors
+      if @_interaction_runtime_errors
+        errors.merge!(@_interaction_runtime_errors)
+      end
+    end
+
+    #
+    module ClassMethods
+      def new(*)
+        super.tap do |instance|
+          {
+            :@_interaction_errors => Errors.new(instance),
+            :@_interaction_result => nil,
+            :@_interaction_runtime_errors => nil
+          }.each do |symbol, obj|
+            instance.instance_variable_set(symbol, obj)
+          end
+        end
+      end
+
+      # @param (see Runnable#initialize)
+      #
+      # @return [Runnable]
+      def run(*args)
+        new(*args).tap { |instance| instance.send(:run) }
+      end
+
+      # @param (see Runnable#initialize)
+      #
+      # @return (see Runnable#run!)
+      #
+      # @raise (see Runnable#run!)
+      def run!(*args)
+        new(*args).send(:run!)
+      end
+    end
+  end
+end

data/lib/active_interaction/errors.rb

@@ -1,63 +1,90 @@
 # coding: utf-8
 
-# rubocop:disable Documentation
+#
 module ActiveInteraction
   # Top-level error class. All other errors subclass this.
+  #
+  # @return [Class]
   Error = Class.new(StandardError)
 
   # Raised if a class name is invalid.
+  #
+  # @return [Class]
   InvalidClassError = Class.new(Error)
 
   # Raised if a default value is invalid.
+  #
+  # @return [Class]
   InvalidDefaultError = Class.new(Error)
 
   # Raised if a filter has an invalid definition.
+  #
+  # @return [Class]
   InvalidFilterError = Class.new(Error)
 
   # Raised if an interaction is invalid.
+  #
+  # @return [Class]
   InvalidInteractionError = Class.new(Error)
 
   # Raised if a user-supplied value is invalid.
+  #
+  # @return [Class]
   InvalidValueError = Class.new(Error)
 
   # Raised if a filter cannot be found.
+  #
+  # @return [Class]
   MissingFilterError = Class.new(Error)
 
   # Raised if no value is given.
+  #
+  # @return [Class]
   MissingValueError = Class.new(Error)
 
   # Raised if there is no default value.
+  #
+  # @return [Class]
   NoDefaultError = Class.new(Error)
 
+  # Used by {Runnable} to signal a failure when composing.
+  #
   # @private
-  Interrupt = Class.new(::Interrupt)
+  class Interrupt < Error
+    attr_reader :outcome
+
+    # @param outcome [Runnable]
+    def initialize(outcome)
+      super()
+
+      @outcome = outcome
+    end
+  end
   private_constant :Interrupt
 
-  # A small extension to provide symbolic error messages to make introspecting
+  # An extension that provides symbolic error messages to make introspection
   #   and testing easier.
-  #
-  # @since 0.6.0
   class Errors < ActiveModel::Errors
-    # A hash mapping attributes to arrays of symbolic messages.
+    # Maps attributes to arrays of symbolic messages.
     #
     # @return [Hash{Symbol => Array<Symbol>}]
     attr_reader :symbolic
 
     # Adds a symbolic error message to an attribute.
     #
-    # @param attribute [Symbol] The attribute to add an error to.
-    # @param symbol [Symbol] The symbolic error to add.
-    # @param message [String, Symbol, Proc]
-    # @param options [Hash]
-    #
-    # @example Adding a symbolic error.
+    # @example
     #   errors.add_sym(:attribute)
     #   errors.symbolic
     #   # => {:attribute=>[:invalid]}
     #   errors.messages
     #   # => {:attribute=>["is invalid"]}
     #
-    # @return [Hash{Symbol => Array<Symbol>}]
+    # @param attribute [Symbol] The attribute to add an error to.
+    # @param symbol [Symbol, nil] The symbolic error to add.
+    # @param message [String, Symbol, Proc, nil] The message to add.
+    # @param options [Hash]
+    #
+    # @return (see #symbolic)
     #
     # @see ActiveModel::Errors#add
     def add_sym(attribute, symbol = :invalid, message = nil, options = {})
@@ -67,21 +94,30 @@ module ActiveInteraction
       symbolic[attribute] << symbol
     end
 
+    # @see ActiveModel::Errors#initialize
+    #
     # @private
-    def initialize(*args)
+    def initialize(*)
       @symbolic = {}.with_indifferent_access
+
       super
     end
 
+    # @see ActiveModel::Errors#initialize_dup
+    #
     # @private
     def initialize_dup(other)
       @symbolic = other.symbolic.with_indifferent_access
+
       super
     end
 
+    # @see ActiveModel::Errors#clear
+    #
     # @private
     def clear
       symbolic.clear
+
       super
     end
 

data/lib/active_interaction/filter.rb

@@ -4,15 +4,13 @@ require 'active_support/inflector'
 
 module ActiveInteraction
   # @!macro [new] filter_method_params
-  #   @param *attributes [Array<Symbol>] attributes to create
+  #   @param *attributes [Array<Symbol>] Attributes to create.
   #   @param options [Hash{Symbol => Object}]
   #
-  #   @option options [Object] :default fallback value if `nil` is given
-  #   @option options [String] :desc human-readable description of this input
+  #   @option options [Object] :default Fallback value if `nil` is given.
+  #   @option options [String] :desc Human-readable description of this input.
 
   # Describes an input filter for an interaction.
-  #
-  # @since 0.6.0
   class Filter
     # @return [Regexp]
     CLASS_REGEXP = /\AActiveInteraction::([A-Z]\w*)Filter\z/
@@ -22,7 +20,7 @@ module ActiveInteraction
     CLASSES = {}
     private_constant :CLASSES
 
-    # @return [Filters]
+    # @return [Hash{Symbol => Filter}]
     attr_reader :filters
 
     # @return [Symbol]
@@ -31,10 +29,6 @@ module ActiveInteraction
     # @return [Hash{Symbol => Object}]
     attr_reader :options
 
-    # Filters that allow sub-filters, like arrays and hashes, must be able to
-    #   use `hash` as a part of their DSL. To keep things consistent, `hash` is
-    #   undefined on all filters. Realistically, {#name} should be unique
-    #   enough to use in place of {#hash}.
     undef_method :hash
 
     class << self
@@ -43,7 +37,6 @@ module ActiveInteraction
       # @example
       #   ActiveInteraction::Filter.factory(:boolean)
       #   # => ActiveInteraction::BooleanFilter
-      #
       # @example
       #   ActiveInteraction::Filter.factory(:invalid)
       #   # => ActiveInteraction::MissingFilterError: :invalid
@@ -52,7 +45,7 @@ module ActiveInteraction
       #
       # @return [Class]
       #
-      # @raise [MissingFilterError] if the slug doesn't map to a filter
+      # @raise [MissingFilterError] If the slug doesn't map to a filter.
       #
       # @see .slug
       def factory(slug)
@@ -66,14 +59,13 @@ module ActiveInteraction
       # @example
       #   ActiveInteraction::BooleanFilter.slug
       #   # => :boolean
-      #
       # @example
       #   ActiveInteraction::Filter.slug
       #   # => ActiveInteraction::InvalidClassError: ActiveInteraction::Filter
       #
       # @return [Symbol]
       #
-      # @raise [InvalidClassError] if the filter doesn't have a valid slug
+      # @raise [InvalidClassError] If the filter doesn't have a valid slug.
       #
       # @see .factory
       def slug
@@ -82,6 +74,8 @@ module ActiveInteraction
         match.captures.first.underscore.to_sym
       end
 
+      # @param klass [Class]
+      #
       # @private
       def inherited(klass)
         CLASSES[klass.slug] = klass
@@ -93,11 +87,11 @@ module ActiveInteraction
     # @param name [Symbol]
     # @param options [Hash{Symbol => Object}]
     #
-    # @option options [Object] :default fallback value to use if `nil` is given
+    # @option options [Object] :default Fallback value to use when given `nil`.
     def initialize(name, options = {}, &block)
       @name = name
       @options = options.dup
-      @filters = Filters.new
+      @filters = {}
 
       instance_eval(&block) if block_given?
     end
@@ -108,29 +102,22 @@ module ActiveInteraction
     # @example
     #   ActiveInteraction::Filter.new(:example).clean(nil)
     #   # => ActiveInteraction::MissingValueError: example
-    #
     # @example
     #   ActiveInteraction::Filter.new(:example).clean(0)
     #   # => ActiveInteraction::InvalidValueError: example: 0
-    #
     # @example
     #   ActiveInteraction::Filter.new(:example, default: nil).clean(nil)
     #   # => nil
-    #
     # @example
     #   ActiveInteraction::Filter.new(:example, default: 0).clean(nil)
-    #   # => ActiveInteraction::InvalidDefault: example: 0
+    #   # => ActiveInteraction::InvalidDefaultError: example: 0
     #
     # @param value [Object]
     #
     # @return [Object]
     #
-    # @raise [InvalidValueError] if the value is invalid
-    # @raise [MissingValueError] if the value is missing and the input is
-    #   required
+    # @raise (see #cast)
     # @raise (see #default)
-    #
-    # @see #default
     def clean(value)
       value = cast(value)
       if value.nil?
@@ -143,23 +130,21 @@ module ActiveInteraction
     # Get the default value.
     #
     # @example
+    #   ActiveInteraction::Filter.new(:example).default
+    #   # => ActiveInteraction::NoDefaultError: example
+    # @example
     #   ActiveInteraction::Filter.new(:example, default: nil).default
     #   # => nil
-    #
     # @example
     #   ActiveInteraction::Filter.new(:example, default: 0).default
     #   # => ActiveInteraction::InvalidDefaultError: example: 0
     #
-    # @example
-    #   ActiveInteraction::Filter.new(:example).default
-    #   # => ActiveInteraction::NoDefaultError: example
-    #
     # @return [Object]
     #
-    # @raise [InvalidDefaultError] if the default value is invalid
-    # @raise [NoDefaultError] if there is no default value
+    # @raise [NoDefaultError] If the default is missing.
+    # @raise [InvalidDefaultError] If the default is invalid.
     def default
-      fail NoDefaultError, name unless has_default?
+      fail NoDefaultError, name unless default?
 
       cast(options[:default])
     rescue InvalidValueError, MissingValueError
@@ -169,12 +154,10 @@ module ActiveInteraction
     # Get the description.
     #
     # @example
-    #   ActiveInteraction::Filter.new(:example, desc: 'description').desc
-    #   # => "description"
-    #
-    # @return [String, nil] the description
+    #   ActiveInteraction::Filter.new(:example, desc: 'Description!').desc
+    #   # => "Description!"
     #
-    # @since 0.8.0
+    # @return [String, nil]
     def desc
       options[:desc]
     end
@@ -182,25 +165,30 @@ module ActiveInteraction
     # Tells if this filter has a default value.
     #
     # @example
-    #   filter = ActiveInteraction::Filter.new(:example)
-    #   filter.has_default?
+    #   ActiveInteraction::Filter.new(:example).default?
     #   # => false
-    #
     # @example
-    #   filter = ActiveInteraction::Filter.new(:example, default: nil)
-    #   filter.has_default?
+    #   ActiveInteraction::Filter.new(:example, default: nil).default?
     #   # => true
     #
     # @return [Boolean]
-    def has_default?
+    def default?
       options.key?(:default)
     end
 
+    # @param value [Object]
+    #
+    # @return [Object]
+    #
+    # @raise [MissingValueError] If the value is missing and there is no
+    #   default.
+    # @raise [InvalidValueError] If the value is invalid.
+    #
     # @private
     def cast(value)
       case value
       when NilClass
-        fail MissingValueError, name unless has_default?
+        fail MissingValueError, name unless default?
 
         nil
       else