active_interaction 3.8.3 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 883e2c22dbe4db00730bd2d917d7812e6f79898f41cfdcde16bc685b1ae1de29
-  data.tar.gz: 4c1af0be75d96c6801b288b450d260580b3d12f330ebeb69b1f6b20d88da5241
+  metadata.gz: acc5f59cdd588429a58556cea7b70aa0c43a6a13c523a682cac266cfc7ab76a1
+  data.tar.gz: 9a58db1735b436ae91a70baf9c2eab9ef4851a20a9e51c05c6f243af6e3c282b
 SHA512:
-  metadata.gz: d2426683e3249c63760a59a25c0a7e8d21780bedf31218676ffca3d75903db0f4b73c18d80b78bbc568997ca67106490bac774bf43f68dacbe5ba00541e08e78
-  data.tar.gz: 412ae553643fd1449c9063058f5d4b8f39ea0bb97f4f166db73bee7ae6bf70a5f01b4ca8ee08a867417b8f7d83d57845d5168383c5ac69d2a931df7490527056
+  metadata.gz: c78b1f82d8593a238a2076f7351146e51079d163d963cc830d9e086bbc82bd791fbc95527d4fc829e3c38039bb77ce06fefe82520f5b6f2148a64384a8e3a339
+  data.tar.gz: 362a8b86512c8ef05d9582a377000e06e2b8b0855c112458020911fa77477c3c98cd10555e81d259cfc767f79c1eb8b03e9ec12124cfca38c552208006e1a70a

data/CHANGELOG.md

@@ -1,3 +1,157 @@
+# [4.0.0][] (2021-01-10)
+
+## Changed
+
+- drop support for Ruby < 2.5, added support for Ruby 3.0
+- drop support for Rails < 5.0, added support for Rails 6.1
+- [#398][] - Predicate methods have been removed.
+  ([how to upgrade](#predicate-methods))
+- [#412][] - Filters will now treat blank string values as `nil`
+  (except `string` and `symbol`). ([how to upgrade](#blank-values-treated-as-nil-for-filters))
+- [#392][] - Integer parsing now defaults the base to 10.
+  ([how to upgrade](#integer-parsing-base-now-10))
+- The `inputs` method now returns an `ActiveInteraction::Input` instead of a
+  hash. The `ActiveInteraction::Input` class still responds to all hash methods.
+- The `object` and `record` filters now only accept an instance of the correct
+  class type or a subclass of the correct class. They no longer allow you to
+  check for included modules. ([how to upgrade](#object-and-record-filter-changes))
+- The `interface` filter will now look for an ancestor of the value passed
+  based on the name of the interface or the value passed in the `from` option.
+- The `InvalidClassError` has been replaced by `InvalidNameError`.
+- When introspecting an array filter, the inner filter is referenced by :'0'
+  instead of the singularized version of the array filter name.
+
+## Added
+
+- Implicit coercion of types are now supported in filters (e.g. to_str, to_int,
+  etc).
+- The `interface` and `record` filters, when used as an inner filter for an
+  `array`, will have their `from/class` option set to a singularized version of
+  the `array` filter name.
+
+## Upgrading
+
+### Predicate Methods
+
+We've removed the predicate methods that were automatically generated for each
+input. They would return true if an input was not `nil`.  They can be manually
+replaced with that same check.
+
+```ruby
+# v3.8
+class Example < ActiveInteraction::Base
+  string :first_name
+
+  validates :first_name,
+    presence: true,
+    if: :first_name?
+
+  def execute
+    # ...
+  end
+end
+
+# v4.0
+class Example < ActiveInteraction::Base
+  string :first_name
+
+  validates :first_name,
+    presence: true,
+    unless: 'first_name.nil?'
+
+  def execute
+    # ...
+  end
+end
+```
+
+## Blank Values Treated As `nil` For Filters
+
+In an effort to improve form support, strings that are `blank?` will
+be converted into `nil` for all filters except `string` and `symbol`.
+Previously, blank strings would have cased `:invalid_type` errors but
+they'll now cause a `:missing` error which should be more form
+friendly. If the filter has a default, the blank string will cause
+the default to be used.
+
+```ruby
+class Example < ActiveInteraction::Base
+  integer :i
+  boolean :b, default: false
+
+  def execute
+    [i, b]
+  end
+end
+
+# v3.8
+Example.run(i: '', b: '').errors.details
+=> {:i=>[{:error=>:invalid_type, :type=>"integer"}], :b=>[{:error=>:invalid_type, :type=>"boolean"}]}
+
+# v4.0
+Example.run(i: '', b: '').errors.details
+=> {:i=>[{:error=>:missing}]}
+
+# v3.8
+Example.run(i: 0, b: '').errors.details
+=> {:b=>[{:error=>:invalid_type, :type=>"boolean"}]}
+
+# v4.0
+Example.run(i: 0, b: '').errors.details
+=> {}
+
+Example.run(i: 0, b: '').result
+=> [0, false] # the default is used for `:b`
+```
+
+### Integer Parsing Base Now 10
+
+Integers are parsed using `Integer`. By default this meant that when
+strings were parsed, radix indicators (0, 0b, and 0x) were honored. Now
+we're defaulting the base to `10`. This means all strings will be parsed
+as though they are base 10.
+
+```ruby
+class Example < ActiveInteraction::Base
+  integer :x
+
+  def execute
+    x
+  end
+end
+
+# v3.8
+Example.run!(x: '010')
+# => 8
+
+# v4.0
+Example.run!(x: '010')
+# => 10
+```
+
+If you want the old behavior that respected the radix you can pass `0`
+as the base.
+
+```diff
+- integer :x
++ integer :x, base: 0
+```
+
+With that change, we can see the radix is respected again.
+
+```ruby
+# v4.0.0
+Example.run!(x: '010')
+# => 8
+```
+
+### Object and Record Filter Changes
+
+The `object` and `record` filters used to be able to check for included modules
+in addition to a class type. This has been removed. If you want any object that
+has a particular module included, you'll need to use the newly expanded
+`interface` filter.
+
 # [3.8.3][] (2020-04-22)
 
 ## Fixed
@@ -777,6 +931,7 @@ Example.run
 
 - Initial release.
 
+  [4.0.0]: https://github.com/AaronLasseigne/active_interaction/compare/v3.8.3...v4.0.0
   [3.8.3]: https://github.com/AaronLasseigne/active_interaction/compare/v3.8.2...v3.8.3
   [3.8.2]: https://github.com/AaronLasseigne/active_interaction/compare/v3.8.1...v3.8.2
   [3.8.1]: https://github.com/AaronLasseigne/active_interaction/compare/v3.8.0...v3.8.1
@@ -979,3 +1134,5 @@ Example.run
   [#476]: https://github.com/AaronLasseigne/active_interaction/issues/476
   [#479]: https://github.com/AaronLasseigne/active_interaction/issues/479
   [#486]: https://github.com/AaronLasseigne/active_interaction/issues/486
+  [#392]: https://github.com/AaronLasseigne/active_interaction/issues/392
+  [#398]: https://github.com/AaronLasseigne/active_interaction/issues/398

data/README.md

@@ -4,7 +4,7 @@ ActiveInteraction manages application-specific business logic.
 It's an implementation of the command pattern in Ruby.
 
 [![Version](https://img.shields.io/gem/v/active_interaction.svg?style=flat-square)](https://rubygems.org/gems/active_interaction)
-[![Build](https://img.shields.io/travis/AaronLasseigne/active_interaction.svg?style=flat-square)](https://travis-ci.org/AaronLasseigne/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)
 [![Coverage](https://img.shields.io/coveralls/github/AaronLasseigne/active_interaction.svg?style=flat-square)](https://coveralls.io/r/orgsync/active_interaction)
 [![Climate](https://img.shields.io/codeclimate/maintainability/orgsync/active_interaction.svg?style=flat-square)](https://codeclimate.com/github/orgsync/active_interaction)
 
@@ -55,7 +55,6 @@ handles your verbs.
   - [Forms](#forms)
   - [Grouped inputs](#grouped-inputs)
   - [Optional inputs](#optional-inputs)
-  - [Predicates](#predicates)
   - [Translations](#translations)
 - [Credits](#credits)
 
@@ -66,23 +65,19 @@ handles your verbs.
 Add it to your Gemfile:
 
 ``` rb
-gem 'active_interaction', '~> 3.8'
+gem 'active_interaction', '~> 4.0'
 ```
 
 Or install it manually:
 
 ``` sh
-$ gem install active_interaction --version '~> 3.8'
+$ gem install active_interaction --version '~> 4.0'
 ```
 
 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][].
 
-ActiveInteraction works with Ruby 2.0 through 2.6 and ActiveModel 4.0 through
-6.0. If you want to use ActiveInteraction with an older version of Ruby or
-ActiveModel, use ActiveInteraction < 3.0.0.
-
 ## Basic usage
 
 To define an interaction, create a subclass of `ActiveInteraction::Base`. Then
@@ -241,7 +236,8 @@ ArrayInteraction.run!(toppings: [:cheese, 'pepperoni'])
 # => 2
 ```
 
-Use a block to constrain the types of elements an array can contain.
+Use a block to constrain the types of elements an array can contain. Note that
+you can only have one filter inside an array block, and it must not have a name.
 
 ``` rb
 array :birthdays do
@@ -249,19 +245,29 @@ array :birthdays do
 end
 ```
 
-Note that you can only have one filter inside an array block, and it must not
-have a name.
+For `interface`, `object`, and `record` filters, the name of the array filter
+will be singularized and used to determine the type of value passed. In the
+example below, the objects passed would need to be of type `Cow`.
 
 ``` rb
 array :cows do
-  object class: Cow
+  object
+end
+```
+
+You can override this by passing the necessary information to the inner filter.
+
+```ruby
+array :managers do
+  object class: People
 end
 ```
 
 ### Boolean
 
-Boolean filters convert the strings `"1"` and `"true"` (case-insensitive) into
-`true`. They also convert `"0"` and `"false"` into `false`.
+Boolean filters convert the strings `"1"`, `"true"`, and `"on"`
+(case-insensitive) into `true`. They also convert `"0"`, `"false"`, and `"off"`
+into `false`. Blank strings will be treated as `nil`.
 
 ``` rb
 class BooleanInteraction < ActiveInteraction::Base
@@ -353,8 +359,45 @@ hash :stuff,
 
 ### Interface
 
-Interface filters allow you to specify that an object must respond to a certain
-set of methods. This allows you to do duck typing with interactions.
+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
@@ -378,30 +421,10 @@ InterfaceInteraction.run!(serializer: JSON)
 # => "{\"is_json\":true}"
 ```
 
-NOTE: The `methods` option is optional.
-
-```rb
-class InterfaceInteraction < ActiveInteraction::Base
-  interface :anything
-
-  def execute
-    anything.class
-  end
-end
-
-require 'json'
-
-InterfaceInteraction.run!(anything: Hash.new)
-# => Hash
-InterfaceInteraction.run!
-# => NilClass
-```
-
 ### Object
 
-Object filters allow you to require an instance of a particular class. It
-checks either `#is_a?` on the instance or `.===` on the class. Because of that,
-it also works with classes that have mixed modules in with `include`.
+Object filters allow you to require an instance of a particular class or one of
+its subclasses.
 
 ``` rb
 class Cow
@@ -438,8 +461,8 @@ object :dolly3,
 ```
 
 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 does
-not pass `#is_a?` and `.===` for the object class. The `converter` option
+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
@@ -466,13 +489,13 @@ ObjectInteraction.run!(ip_address: 1)
 
 ### Record
 
-Record filters allow you to require an instance of a particular class or a value
-that can be used to locate an instance of the object. It checks either `#is_a?`
-on the instance or `.===` on the class. 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.
+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
@@ -542,9 +565,10 @@ SymbolInteraction.run!(method: :object_id)
 ### 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`. 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.
+convert strings into their expected data types using `.parse`. Blank strings
+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
 
@@ -618,7 +642,8 @@ time :start,
 ### Numbers
 
 All numeric filters accept numeric input. They will also convert strings using
-the appropriate method from `Kernel` (like `.Float`).
+the appropriate method from `Kernel` (like `.Float`). Blank strings will be
+treated as `nil`.
 
 #### Decimal
 
@@ -679,24 +704,27 @@ IntegerInteraction.run!(limit: 10)
 ```
 
 When a `String` is passed into an `integer` input, the value will be coerced.
-Coercion is based on `Kernel#Integer` which attempts to detect the base being used.
-However, you may want to specify the `base` for the conversion to something more
-sensible (e.g. `base: 10`).
+A default base of `10` is used though it may be overridden with the `base` option.
+If a base of `0` is provided, the coercion will respect radix indicators present
+in the string.
 
 ``` rb
 class IntegerInteraction < ActiveInteraction::Base
-  integer :limit1, base: 10
-  integer :limit2
+  integer :limit1
+  integer :limit2, base: 8
+  integer :limit3, base: 0
 
   def execute
-    [limit1, limit2]
+    [limit1, limit2, limit3]
   end
 end
 
-IntegerInteraction.run!(limit1: "08", limit2: 8)
-# => [8, 8]
-IntegerInteraction.run!(limit1: "08", limit2: "08")
-# ArgumentError: invalid value for Integer(): "08"
+IntegerInteraction.run!(limit1: 71, limit2: 71, limit3: 71)
+# => [71, 71, 71]
+IntegerInteraction.run!(limit1: "071", limit2: "071", limit3: "0x71")
+# => [71, 57, 113]
+IntegerInteraction.run!(limit1: "08", limit2: "08", limit3: "08")
+ActiveInteraction::InvalidInteractionError: Limit2 is not a valid integer, Limit3 is not a valid integer
 ```
 
 ## Rails
@@ -940,10 +968,6 @@ The interaction that updates accounts is more complicated than the others. It
 requires an account to update, but the other inputs are optional. If they're
 missing, it'll ignore those attributes. If they're present, it'll update them.
 
-ActiveInteraction generates predicate methods (like `#first_name?`) for your
-inputs. They will return `false` if the input is `nil` and `true` otherwise.
-Skip to [the predicates section](#predicates) for more information about them.
-
 ``` rb
 class UpdateAccount < ActiveInteraction::Base
   object :account
@@ -953,14 +977,14 @@ class UpdateAccount < ActiveInteraction::Base
 
   validates :first_name,
     presence: true,
-    if: :first_name?
+    unless: 'first_name.nil?'
   validates :last_name,
     presence: true,
-    if: :last_name?
+    unless: 'last_name.nil?'
 
   def execute
-    account.first_name = first_name if first_name?
-    account.last_name = last_name if last_name?
+    account.first_name = first_name if first_name.present?
+    account.last_name = last_name if last_name.present?
 
     unless account.save
       errors.merge!(account.errors)
@@ -1177,9 +1201,6 @@ def execute
 end
 ```
 
-These types of errors will become standard with Rails 5. ActiveInteraction's
-implementation is based off of [active_model-errors_details][].
-
 ActiveInteraction also supports merging errors. This is useful if you want to
 delegate validation to some other object. For example, if you have an
 interaction that updates a record, you might want that record to validate
@@ -1375,41 +1396,6 @@ UpdateUser.run!(user: user, birthday: nil)
 UpdateUser.run!(user: user, birthday: Date.new(2000, 1, 2))
 ```
 
-### Predicates
-
-ActiveInteraction creates a predicate method for every input defined by a
-filter. So if you have an input called `foo`, there will be a predicate method
-called `#foo?`. That method will tell you if the input was given (that is, if
-it was not `nil`).
-
-``` rb
-class SayHello < ActiveInteraction::Base
-  string :name,
-    default: nil
-
-  def execute
-    if name?
-      "Hello, #{name}!"
-    else
-      "Howdy, stranger!"
-    end
-  end
-end
-
-SayHello.run!(name: nil)
-# => "Howdy, stranger!"
-SayHello.run!(name: 'Taylor')
-# => "Hello, Taylor!"
-```
-
-This can be confusing for boolean inputs. If you have some boolean input `foo`,
-then the actual value of that input is available through `foo`. The associated
-predicate method, `#foo?`, will tell you if that value is not `nil`. So it will
-only be `false` if the input is optional and happens to be `nil`.
-
-See [the optional inputs section][] for help on determining if an input was
-present in the input hash instead of just `nil`.
-
 ### Translations
 
 ActiveInteraction is i18n aware out of the box! All you have to do is add