active_interaction 4.1.0 → 5.1.1

data/README.md

@@ -1,7 +1,7 @@
 # [ActiveInteraction][]
 
 ActiveInteraction manages application-specific business logic.
-It's an implementation of the command pattern in Ruby.
+It's an implementation of service objects designed to blend seamlessly into Rails.
 
 [![Version](https://img.shields.io/gem/v/active_interaction.svg?style=flat-square)](https://rubygems.org/gems/active_interaction)
 [![Test](https://img.shields.io/github/workflow/status/AaronLasseigne/active_interaction/Test?label=Test&style=flat-square)](https://github.com/AaronLasseigne/active_interaction/actions?query=workflow%3ATest)
@@ -17,23 +17,25 @@ handles your verbs.
 - [Basic usage](#basic-usage)
   - [Validations](#validations)
 - [Filters](#filters)
-  - [Array](#array)
-  - [Boolean](#boolean)
-  - [File](#file)
-  - [Hash](#hash)
-  - [Interface](#interface)
-  - [Object](#object)
-  - [Record](#record)
-  - [String](#string)
-  - [Symbol](#symbol)
-  - [Dates and times](#dates-and-times)
-    - [Date](#date)
-    - [DateTime](#datetime)
-    - [Time](#time)
-  - [Numbers](#numbers)
-    - [Decimal](#decimal)
-    - [Float](#float)
-    - [Integer](#integer)
+  - [Basic Filters](#basic-filters)
+    - [Array](#array)
+    - [Boolean](#boolean)
+    - [File](#file)
+    - [Hash](#hash)
+    - [String](#string)
+    - [Symbol](#symbol)
+    - [Dates and times](#dates-and-times)
+      - [Date](#date)
+      - [DateTime](#datetime)
+      - [Time](#time)
+    - [Numbers](#numbers)
+      - [Decimal](#decimal)
+      - [Float](#float)
+      - [Integer](#integer)
+  - [Advanced Filters](#advanced-filters)
+    - [Interface](#interface)
+    - [Object](#object)
+    - [Record](#record)
 - [Rails](#rails)
   - [Setup](#setup)
   - [Controller](#controller)
@@ -51,7 +53,7 @@ handles your verbs.
   - [Descriptions](#descriptions)
   - [Errors](#errors)
   - [Forms](#forms)
-  - [Grouped inputs](#grouped-inputs)
+  - [Shared input options](#shared-input-options)
   - [Optional inputs](#optional-inputs)
   - [Translations](#translations)
 - [Credits](#credits)
@@ -63,18 +65,17 @@ handles your verbs.
 Add it to your Gemfile:
 
 ``` rb
-gem 'active_interaction', '~> 4.1'
+gem 'active_interaction', '~> 5.1'
 ```
 
 Or install it manually:
 
 ``` sh
-$ gem install active_interaction --version '~> 4.1'
+$ gem install active_interaction --version '~> 5.1'
 ```
 
 This project uses [Semantic Versioning][]. Check out [GitHub releases][] for a
-detailed list of changes. For help upgrading to version 2, please read [the
-announcement post][].
+detailed list of changes.
 
 ## Basic usage
 
@@ -89,7 +90,7 @@ you need to do two things:
 2.  **Define your business logic.** Do this by implementing the `#execute`
     method. Each input you defined will be available as the type you specified.
     If any of the inputs are invalid, `#execute` won't be run. Filters are
-    responsible for type checking your inputs. Check out [the validations
+    responsible for checking your inputs. Check out [the validations
     section](#validations) if you need more than that.
 
 That covers the basics. Let's put it all together into a simple example that
@@ -141,7 +142,7 @@ Square.run!(x: 2.1)
 
 ### Validations
 
-ActiveInteraction type checks your inputs. Often you'll want more than that.
+ActiveInteraction checks your inputs. Often you'll want more than that.
 For instance, you may want an input to be a string with at least one
 non-whitespace character. Instead of writing your own validation for that, you
 can use validations from ActiveModel.
@@ -164,7 +165,7 @@ end
 ```
 
 When you run this interaction, two things will happen. **First
-ActiveInteraction will type check your inputs. Then ActiveModel will validate
+ActiveInteraction will check your inputs. Then ActiveModel will validate
 them.** If both of those are happy, it will be executed.
 
 ``` rb
@@ -214,7 +215,9 @@ alternatives that can be reasonably coerced. Typically the coercions come from
 Rails, so `"1"` can be interpreted as the boolean value `true`, the string
 `"1"`, or the number `1`.
 
-### Array
+### Basic Filters
+
+#### Array
 
 In addition to accepting arrays, array inputs will convert
 `ActiveRecord::Relation`s into arrays.
@@ -261,7 +264,33 @@ array :managers do
 end
 ```
 
-### Boolean
+Errors that occur will be indexed based on the Rails configuration setting
+`index_nested_attribute_errors`. You can also manually override this setting
+with the `:index_errors` option. In this state is is possible to get multiple
+errors from a single filter.
+
+```ruby
+class ArrayInteraction < ActiveInteraction::Base
+  array :favorite_numbers, index_errors: true do
+    integer
+  end
+
+  def execute
+    favorite_numbers
+  end
+end
+
+ArrayInteraction.run(favorite_numbers: [8, 'bazillion']).errors.details
+=> {:"favorite_numbers[1]"=>[{:error=>:invalid_type, :type=>"array"}]}
+```
+
+With `:index_errors` set to `false` the error would have been:
+
+```ruby
+{:favorite_numbers=>[{:error=>:invalid_type, :type=>"array"}]}
+```
+
+#### Boolean
 
 Boolean filters convert the strings `"1"`, `"true"`, and `"on"`
 (case-insensitive) into `true`. They also convert `"0"`, `"false"`, and `"off"`
@@ -282,7 +311,7 @@ BooleanInteraction.run!(kool_aid: true)
 # => "Oh yeah!"
 ```
 
-### File
+#### File
 
 File filters also accept `TempFile`s and anything that responds to `#rewind`.
 That means that you can pass the `params` from uploading files via forms in
@@ -303,7 +332,7 @@ FileInteraction.run!(readme: File.open('README.md'))
 # => 21563
 ```
 
-### Hash
+#### Hash
 
 Hash filters accept hashes. The expected value types are given by passing a
 block and nesting other filters. You can have any number of filters inside a
@@ -355,165 +384,7 @@ hash :stuff,
   strip: false
 ```
 
-### Interface
-
-Interface filters allow you to specify an interface that the passed value must
-meet in order to pass. The name of the interface is used to look for a constant
-inside the ancestor listing for the passed value. This allows for a variety of
-checks depending on what's passed. Class instances are checked for an included
-module or an inherited ancestor class. Classes are checked for an extended
-module or an inherited ancestor class. Modules are checked for an extended
-module.
-
-``` rb
-class InterfaceInteraction < ActiveInteraction::Base
-  interface :exception
-
-  def execute
-    exception
-  end
-end
-
-InterfaceInteraction.run!(exception: Exception)
-# ActiveInteraction::InvalidInteractionError: Exception is not a valid interface
-InterfaceInteraction.run!(exception: NameError) # a subclass of Exception
-# => NameError
-```
-
-You can use `:from` to specify a class or module. This would be the equivalent
-of what's above.
-
-```rb
-class InterfaceInteraction < ActiveInteraction::Base
-  interface :error,
-    from: Exception
-
-  def execute
-    error
-  end
-end
-```
-
-You can also create an anonymous interface on the fly by passing the `methods`
-option.
-
-``` rb
-class InterfaceInteraction < ActiveInteraction::Base
-  interface :serializer,
-    methods: %i[dump load]
-
-  def execute
-    input = '{ "is_json" : true }'
-    object = serializer.load(input)
-    output = serializer.dump(object)
-
-    output
-  end
-end
-
-require 'json'
-
-InterfaceInteraction.run!(serializer: Object.new)
-# ActiveInteraction::InvalidInteractionError: Serializer is not a valid interface
-InterfaceInteraction.run!(serializer: JSON)
-# => "{\"is_json\":true}"
-```
-
-### Object
-
-Object filters allow you to require an instance of a particular class or one of
-its subclasses.
-
-``` rb
-class Cow
-  def moo
-    'Moo!'
-  end
-end
-
-class ObjectInteraction < ActiveInteraction::Base
-  object :cow
-
-  def execute
-    cow.moo
-  end
-end
-
-ObjectInteraction.run!(cow: Object.new)
-# ActiveInteraction::InvalidInteractionError: Cow is not a valid object
-ObjectInteraction.run!(cow: Cow.new)
-# => "Moo!"
-```
-
-The class name is automatically determined by the filter name. If your filter
-name is different than your class name, use the `class` option. It can be
-either the class, a string, or a symbol.
-
-``` rb
-object :dolly1,
-  class: Sheep
-object :dolly2,
-  class: 'Sheep'
-object :dolly3,
-  class: :Sheep
-```
-
-If you have value objects or you would like to build one object from another,
-you can use the `converter` option. It is only called if the value provided is
-not an instance of the class or one of its subclasses. The `converter` option
-accepts a symbol that specifies a class method on the object class or a proc.
-Both will be passed the value and any errors thrown inside the converter will
-cause the value to be considered invalid. Any returned value that is not the
-correct class will also be treated as invalid. The value given to the `default`
-option will also be converted.
-
-``` rb
-class ObjectInteraction < ActiveInteraction::Base
-  object :ip_address,
-    class: IPAddr,
-    converter: :new
-
-  def execute
-    ip_address
-  end
-end
-
-ObjectInteraction.run!(ip_address: '192.168.1.1')
-# #<IPAddr: IPv4:192.168.1.1/255.255.255.255>
-
-ObjectInteraction.run!(ip_address: 1)
-# ActiveInteraction::InvalidInteractionError: Ip address is not a valid object
-```
-
-### Record
-
-Record filters allow you to require an instance of a particular class (or one
-of its subclasses) or a value that can be used to locate an instance of the
-object. If the value does not match, it will call `find` on the class of the
-record. This is particularly useful when working with ActiveRecord objects.
-Like an object filter, the class is derived from the name passed but can be
-specified with the `class` option. The value given to the `default` option will
-also be found.
-
-``` rb
-class RecordInteraction < ActiveInteraction::Base
-  record :encoding
-
-  def execute
-    encoding
-  end
-end
-
-> RecordInteraction.run!(encoding: Encoding::US_ASCII)
-=> #<Encoding:US-ASCII>
-
-> RecordInteraction.run!(encoding: 'ascii')
-=> #<Encoding:US-ASCII>
-```
-
-A different method can be specified by providing a symbol to the `finder` option.
-
-### String
+#### String
 
 String filters define inputs that only accept strings.
 
@@ -540,7 +411,7 @@ string :comment,
   strip: false
 ```
 
-### Symbol
+#### Symbol
 
 Symbol filters define inputs that accept symbols. Strings will be converted
 into symbols.
@@ -560,7 +431,7 @@ SymbolInteraction.run!(method: :object_id)
 # => #<Proc:0x007fdc9ba94118>
 ```
 
-### Dates and times
+#### Dates and times
 
 Filters that work with dates and times behave similarly. By default, they all
 convert strings into their expected data types using `.parse`. Blank strings
@@ -568,7 +439,7 @@ will be treated as `nil`. If you give the `format` option, they will instead
 convert strings using `.strptime`. Note that formats won't work with `DateTime`
 and `Time` filters if a time zone is set.
 
-#### Date
+##### Date
 
 ``` rb
 class DateInteraction < ActiveInteraction::Base
@@ -590,7 +461,7 @@ date :birthday,
   format: '%Y-%m-%d'
 ```
 
-#### DateTime
+##### DateTime
 
 ``` rb
 class DateTimeInteraction < ActiveInteraction::Base
@@ -612,7 +483,7 @@ date_time :start,
   format: '%Y-%m-%dT%H:%M:%S'
 ```
 
-#### Time
+##### Time
 
 In addition to converting strings with `.parse` (or `.strptime`), time filters
 convert numbers with `.at`.
@@ -637,13 +508,13 @@ time :start,
   format: '%Y-%m-%dT%H:%M:%S'
 ```
 
-### Numbers
+#### Numbers
 
 All numeric filters accept numeric input. They will also convert strings using
 the appropriate method from `Kernel` (like `.Float`). Blank strings will be
 treated as `nil`.
 
-#### Decimal
+##### Decimal
 
 ``` rb
 class DecimalInteraction < ActiveInteraction::Base
@@ -667,7 +538,7 @@ decimal :dollars,
   digits: 2
 ```
 
-#### Float
+##### Float
 
 ``` rb
 class FloatInteraction < ActiveInteraction::Base
@@ -684,7 +555,7 @@ FloatInteraction.run!(x: 2.1)
 # => 4.41
 ```
 
-#### Integer
+##### Integer
 
 ``` rb
 class IntegerInteraction < ActiveInteraction::Base
@@ -725,6 +596,167 @@ IntegerInteraction.run!(limit1: "08", limit2: "08", limit3: "08")
 ActiveInteraction::InvalidInteractionError: Limit2 is not a valid integer, Limit3 is not a valid integer
 ```
 
+### Advanced Filters
+
+#### Interface
+
+Interface filters allow you to specify an interface that the passed value must
+meet in order to pass. The name of the interface is used to look for a constant
+inside the ancestor listing for the passed value. This allows for a variety of
+checks depending on what's passed. Class instances are checked for an included
+module or an inherited ancestor class. Classes are checked for an extended
+module or an inherited ancestor class. Modules are checked for an extended
+module.
+
+``` rb
+class InterfaceInteraction < ActiveInteraction::Base
+  interface :exception
+
+  def execute
+    exception
+  end
+end
+
+InterfaceInteraction.run!(exception: Exception)
+# ActiveInteraction::InvalidInteractionError: Exception is not a valid interface
+InterfaceInteraction.run!(exception: NameError) # a subclass of Exception
+# => NameError
+```
+
+You can use `:from` to specify a class or module. This would be the equivalent
+of what's above.
+
+```rb
+class InterfaceInteraction < ActiveInteraction::Base
+  interface :error,
+    from: Exception
+
+  def execute
+    error
+  end
+end
+```
+
+You can also create an anonymous interface on the fly by passing the `methods`
+option.
+
+``` rb
+class InterfaceInteraction < ActiveInteraction::Base
+  interface :serializer,
+    methods: %i[dump load]
+
+  def execute
+    input = '{ "is_json" : true }'
+    object = serializer.load(input)
+    output = serializer.dump(object)
+
+    output
+  end
+end
+
+require 'json'
+
+InterfaceInteraction.run!(serializer: Object.new)
+# ActiveInteraction::InvalidInteractionError: Serializer is not a valid interface
+InterfaceInteraction.run!(serializer: JSON)
+# => "{\"is_json\":true}"
+```
+
+#### Object
+
+Object filters allow you to require an instance of a particular class or one of
+its subclasses.
+
+``` rb
+class Cow
+  def moo
+    'Moo!'
+  end
+end
+
+class ObjectInteraction < ActiveInteraction::Base
+  object :cow
+
+  def execute
+    cow.moo
+  end
+end
+
+ObjectInteraction.run!(cow: Object.new)
+# ActiveInteraction::InvalidInteractionError: Cow is not a valid object
+ObjectInteraction.run!(cow: Cow.new)
+# => "Moo!"
+```
+
+The class name is automatically determined by the filter name. If your filter
+name is different than your class name, use the `class` option. It can be
+either the class, a string, or a symbol.
+
+``` rb
+object :dolly1,
+  class: Sheep
+object :dolly2,
+  class: 'Sheep'
+object :dolly3,
+  class: :Sheep
+```
+
+If you have value objects or you would like to build one object from another,
+you can use the `converter` option. It is only called if the value provided is
+not an instance of the class or one of its subclasses. The `converter` option
+accepts a symbol that specifies a class method on the object class or a proc.
+Both will be passed the value and any errors thrown inside the converter will
+cause the value to be considered invalid. Any returned value that is not the
+correct class will also be treated as invalid. Any `default` that is not an
+instance of the class or subclass and is not `nil` will also be converted.
+
+``` rb
+class ObjectInteraction < ActiveInteraction::Base
+  object :ip_address,
+    class: IPAddr,
+    converter: :new
+
+  def execute
+    ip_address
+  end
+end
+
+ObjectInteraction.run!(ip_address: '192.168.1.1')
+# #<IPAddr: IPv4:192.168.1.1/255.255.255.255>
+
+ObjectInteraction.run!(ip_address: 1)
+# ActiveInteraction::InvalidInteractionError: Ip address is not a valid object
+```
+
+#### Record
+
+Record filters allow you to require an instance of a particular class (or one
+of its subclasses) or a value that can be used to locate an instance of the
+object. If the value does not match, it will call `find` on the class of the
+record. This is particularly useful when working with ActiveRecord objects.
+Like an object filter, the class is derived from the name passed but can be
+specified with the `class` option. Any `default` that is not an instance of the
+class or subclass and is not `nil` will also be found. Blank strings passed in
+will be treated as `nil`.
+
+``` rb
+class RecordInteraction < ActiveInteraction::Base
+  record :encoding
+
+  def execute
+    encoding
+  end
+end
+
+> RecordInteraction.run!(encoding: Encoding::US_ASCII)
+=> #<Encoding:US-ASCII>
+
+> RecordInteraction.run!(encoding: 'ascii')
+=> #<Encoding:US-ASCII>
+```
+
+A different method can be specified by providing a symbol to the `finder` option.
+
 ## Rails
 
 ActiveInteraction plays nicely with Rails. You can use interactions to handle
@@ -736,10 +768,7 @@ resourceful actions.
 
 We recommend putting your interactions in `app/interactions`. It's also very
 helpful to group them by model. That way you can look in
-`app/interactions/accounts` for all the ways you can interact with accounts. In
-order to use this structure add
-`config.autoload_paths += Dir.glob("#{config.root}/app/interactions/*")` in
-your `application.rb`
+`app/interactions/accounts` for all the ways you can interact with accounts.
 
 ```
 - app/
@@ -842,7 +871,7 @@ end
 ```
 
 Note that it's perfectly fine to add errors during execution. Not all errors
-have to come from type checking or validation.
+have to come from checking or validation.
 
 #### New
 
@@ -1025,7 +1054,7 @@ interaction's lifecycle.
 
 ``` rb
 class Increment < ActiveInteraction::Base
-  set_callback :type_check, :before, -> { puts 'before type check' }
+  set_callback :filter, :before, -> { puts 'before filter' }
 
   integer :x
 
@@ -1047,7 +1076,7 @@ class Increment < ActiveInteraction::Base
 end
 
 Increment.run!(x: 1)
-# before type check
+# before filter
 # after validate
 # >>>
 # executing
@@ -1055,7 +1084,7 @@ Increment.run!(x: 1)
 # => 2
 ```
 
-In order, the available callbacks are `type_check`, `validate`, and `execute`.
+In order, the available callbacks are `filter`, `validate`, and `execute`.
 You can set `before`, `after`, or `around` on any of them.
 
 ### Composition
@@ -1178,7 +1207,7 @@ errors.
 ``` rb
 outcome = BuyItem.run(item: 'Thing', options: { gift_wrapped: 'yes' })
 outcome.errors.messages
-# => {:credit_card=>["is required"], :item=>["is not a valid object"], :options=>["has an invalid nested value (\"gift_wrapped\" => \"yes\")"]}
+# => {:credit_card=>["is required"], :item=>["is not a valid object"], :"options.gift_wrapped"=>["is not a valid boolean"]}
 ```
 
 Determining the type of error based on the string is difficult if not
@@ -1187,7 +1216,7 @@ the same list of errors with a testable label representing the error.
 
 ``` rb
 outcome.errors.details
-# => {:credit_card=>[{:error=>:missing}], :item=>[{:type=>"object", :error=>:invalid_type}], :options=>[{:name=>"\"gift_wrapped\"", :value=>"\"yes\"", :error=>:invalid_nested}]}
+# => {:credit_card=>[{:error=>:missing}], :item=>[{:error=>:invalid_type, :type=>"object"}], :"options.gift_wrapped"=>[{:error=>:invalid_type, :type=>"boolean"}]}
 ```
 
 Detailed errors can also be manually added during the execute call by passing a
@@ -1337,7 +1366,7 @@ used to define the inputs on your interaction will relay type information to
 these gems. As a result, form fields will automatically use the appropriate
 input type.
 
-### Grouped inputs
+### Shared input options
 
 It can be convenient to apply the same options to a bunch of inputs. One common
 use case is making many inputs optional. Instead of setting `default: nil` on
@@ -1358,8 +1387,8 @@ Optional inputs can be defined by using the `:default` option as described in
 are merged to create `inputs`. There are times where it is useful to know
 whether a value was passed to `run` or the result of a filter default. In
 particular, it is useful when `nil` is an acceptable value. For example, you
-may optionally track your users' birthdays. You can use the `given?` predicate
-to see if an input was even passed to `run`. With `given?` you can also check
+may optionally track your users' birthdays. You can use the `inputs.given?` predicate
+to see if an input was even passed to `run`. With `inputs.given?` you can also check
 the input of a hash or array filter by passing a series of keys or indexes to
 check.
 
@@ -1370,7 +1399,7 @@ class UpdateUser < ActiveInteraction::Base
     default: nil
 
   def execute
-    user.birthday = birthday if given?(:birthday)
+    user.birthday = birthday if inputs.given?(:birthday)
     errors.merge!(user.errors) unless user.save
     user
   end
@@ -1424,7 +1453,6 @@ hsilgne:
     errors:
       messages:
         invalid: dilavni si
-        invalid_nested: (%{value} <= %{name}) eulav detsen dilavni na sah
         invalid_type: '%{type} dilav a ton si'
         missing: deriuqer si
 ```
@@ -1444,6 +1472,19 @@ I18nInteraction.run(name: false).errors.messages[:name]
 # => ["gnirts dilav a ton si"]
 ```
 
+Everything else works like an `activerecord` entry. For example, to rename an
+attribute you can use `attributes`.
+
+Here we'll rename the `num` attribute on an interaction named `product`:
+
+``` yml
+en:
+  active_interaction:
+    attributes:
+      product:
+        num: 'Number'
+```
+
 ## Credits
 
 ActiveInteraction is brought to you by [Aaron Lasseigne][].
@@ -1457,13 +1498,13 @@ ActiveInteraction is licensed under [the MIT License][].
 
 [activeinteraction]: https://github.com/AaronLasseigne/active_interaction
 [API Documentation]: http://rubydoc.info/github/AaronLasseigne/active_interaction
-[semantic versioning]: http://semver.org/spec/v2.0.0.html
+[Semantic Versioning]: http://semver.org/spec/v2.0.0.html
 [GitHub releases]: https://github.com/AaronLasseigne/active_interaction/releases
 [aaron lasseigne]: https://github.com/AaronLasseigne
 [taylor fausak]: https://github.com/tfausak
 [our contribution guidelines]: CONTRIBUTING.md
 [complete list of contributors]: https://github.com/AaronLasseigne/active_interaction/graphs/contributors
-[the mit license]: LICENSE.md
+[the MIT License]: LICENSE.md
 [formtastic]: https://rubygems.org/gems/formtastic
 [simple_form]: https://rubygems.org/gems/simple_form
 [the filters section]: #filters