makwa 0.2.1 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a01474a6d7d669f7d02f6ddec9ab653710b4215399e83a429a099b520122838b
-  data.tar.gz: 53d47eff5c8f981119af924a15f6d93a23435af552edb14ee66216e598979ec9
+  metadata.gz: 05d88c5995c722bae7c3769dfafe68dcf56389462b9d0ae6dc1a1fb330bab923
+  data.tar.gz: 6cb8f9358894fa15ab384a760a07bc37a1e6ac2c14dc72286421024b4fd5fb6d
 SHA512:
-  metadata.gz: e20a524264523fdbdc2715994a06ce34d52ca8761f9a8bff5b1a51d92e463a7f5d9850bc35a944c3b67898a82d5530c3512e70497137da571d2240623247e86e
-  data.tar.gz: 88833f8324ad7167e89af8b91d9c71b505b516b7502de9ac74fe70d213e5c69d6b586055f24bb1a89740d46edfc7400d051f2e2d49437cd7217c1e0d88a7b260
+  metadata.gz: 7a5426ce17f47958382bcd42cb203524e2625c9fe67a3f1b3cb3afc371592bc1ca11b4fd8db705d2710bf0c7b75202b762ec8f272d0f3cd5d234581e9c0e63e9
+  data.tar.gz: d71ba78909dd101447aa104d62eb49444c09713bcde3403969ad45a5b566ce10f0da4d7031c53d9aa546cbe1b3f33de6115e060f4a9663b6960e952bc4393d99

data/.gitignore

@@ -8,3 +8,5 @@
 
 Gemfile.lock
 .byebug_history
+
+.DS_Store

data/CHANGELOG.md

@@ -1,14 +1,23 @@
 ## [Unreleased]
 
+## [1.0.1] - 2022-12-01
+
+- Fixes reference to nested class (symbol -> string)
+
+## [1.0.0] - 2022-11-26
+
+- Upgrades ActiveInteraction from 4.x to 5.2.x. Please see the [ActiveInteraction CHANGELOG](https://github.com/AaronLasseigne/active_interaction/blob/main/CHANGELOG.md) for what has changed between v. 4.x and 5. There are some breaking changes.
+- Adds documentation.
+
 ## [0.2.1] - 2021-11-03
 
 - Fixes bug where the `returning` attribute was not ignored correctly when assigning attrs under certain error conditions.
 
 ## [0.2.0] - 2021-10-27
 
-- Adds implementation
-- Updates ReturningInteraction to copy errors and values to returned object on invalid inputs
+- Adds implementation.
+- Updates ReturningInteraction to copy errors and values to returned object on invalid inputs.
 
 ## [0.1.0] - 2021-09-23
 
-- Initial release
+- Initial release.

data/README.md

@@ -1,36 +1,188 @@
 # Makwa
 
-Interactions for Ruby on Rails.
+Makwa is an extension of the [ActiveInteraction](https://github.com/AaronLasseigne/active_interaction) gem, bringing interactions to Ruby on Rails apps.
+
+> ActiveInteraction manages application-specific business logic. It's an implementation of service objects designed to blend seamlessly into Rails. It also helps you write safer code by validating that your inputs conform to your expectations. If ActiveModel deals with your nouns, then ActiveInteraction handles your verbs.
+
+<p align="right">Readme for ActiveInteraction.</p>
+
+Makwa improves the ergonomics around mutating ActiveRecord instances.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'makwa'
+gem "makwa"
 ```
 
 And then execute:
 
-    $ bundle install
+```shell
+$ bundle install
+```
 
 Or install it yourself as:
 
-    $ gem install makwa
+```shell
+$ gem install makwa
+```
+
+Makwa extends the ActiveInteraction gem and will install it automatically as a dependency.
+
+Makwa is compatible with Ruby 2.7 or greater and Rails 5 or greater.
+
+## What does Makwa add to ActiveInteraction?
+
+Please read through the [ActiveInteraction Readme](https://github.com/AaronLasseigne/active_interaction) first and then come back here to see what Makwa adds to ActiveInteraction:
+
+### ReturningInteraction
+
+ReturningInteractions are a special kind of interaction, optimized for usage with Rails forms:
+
+The basic approach of ActiveInteraction (AI) when rendering ActiveRecord model forms is to pass an AI instance to the form. That approach works great for simple mutations of ActiveRecord instances. However, for this to work, the AI class has to implement all methods required for rendering your forms. That can get tricky when you need to traverse associations, or call complex decorators on your models. This approach also fails if the interaction's `#execute` method is never run because the input validations fail.
+
+ReturningInteraction (RI) chooses a different approach: It accepts the to-be-mutated ActiveRecord instance as an input argument and is guaranteed to return that instance, no matter if the interaction outcome is successful or not. The RI will merge all errors that occurred during execution to the returned ActiveRecord instance. This allows you to pass the actual ActiveRecord instance to your form, and you don't have to implement all methods required for the form to be rendered.
+
+Let's look at some example code to see the difference:
+
+The ActiveInteraction way
+
+```ruby
+# app/controllers/users_controller.rb
+class UsersController < ApplicationController
+  def new
+    @user = User.new
+  end
+
+  def create
+    outcome = Users::Create.run(
+      params.fetch(:user, {})
+    )
+
+    if outcome.valid?
+      redirect_to(outcome.result)
+    else
+      @user = outcome
+      render(:new)
+    end
+  end
+end
+
+# app/interactions/users/create.rb
+module Users
+  class Create < ApplicationInteraction
+    string :first_name
+    string :last_name
+    array :role_ids, default: []
+
+    def execute
+      user = User.new(inputs)
+      errors.merge!(user.errors) unless user.save
+      user
+    end
+
+    def to_model
+      User.new
+    end
+  end
+end
+```
+
+The Makwa way
+
+```ruby
+# app/controllers/users_controller.rb
+class UsersController < ApplicationController
+  def new
+    @user = User.new
+  end
+
+  def create
+    # Differences: Pass in the `:user` input and call `#run_returning!` instead of `#run`.
+    @user = Users::Create.run_returning!(
+      {user: User.new}.merge(params.fetch(:user, {}))
+    )
+
+    if @user.errors_empty?
+      redirect_to(@user)
+    else
+      render(:new)
+    end
+  end
+end
+
+# app/interactions/users/create.rb
+module Users
+  class Create < ApplicationReturningInteraction
+    returning :user # This is different from AI: Specifies which input will be returned.
+
+    string :first_name
+    string :last_name
+    string :email
+    record :user
+
+    def execute_returning # Notice: Method is called `execute_returning`, not `execute`!
+      user.update(inputs.except(:user))
+      # No need to merge any errors. This will be done automatically by Makwa
+      return_if_errors!
+
+      compose(
+        Infrastructure::SendEmail,
+        recipient_email: user.email,
+        subject: "Welcome to Makwa",
+        body: "Lorem ipsum..."
+      )
+      # No need for an explicit return of user, also done by Makwa
+      # (via `returning` input filter).
+    end
+
+    # No need to implement the `#to_model` method and any other methods required to
+    # render your forms.
+  end
+end
+```
+
+### Other improvements
+
+Makwa offers **safe ways to check for errors**. Instead of `#valid?` or `#invalid?` use `#errors_empty?` or `#errors_any?`. Rails' `#valid?` method is a destructive method that will clear all errors and re-run validations. This will eradicate any errors you added in the body of the `#execute` or `#execute_returning` methods.
+
+Makwa offers a simple way to **exit early** from the interaction. Use `#return_if_errors!` at any point in the `#execute` method if errors make it impossible to continue execution of the interaction.
+
+Makwa offers **detailed logging** around interaction invocations (with inputs) and outcomes (with errors):
+
+```
+Executing interaction Users::SendWelcomeEmail (id#1234567)
+ ↳ called from Users::Create (id#7654321)
+ ↳ inputs: {first_name: "Giselher", last_name: "Wulla"} (id#7654321)
+ # ... execute interaction
+ ↳ outcome: failed (id#7654321)
+ ↳ errors: "Email is missing" (id#7654321)
+```
+
+To enable debug logging just define this method in your `ApplicationInteraction`:
+
+```ruby
+def debug(txt)
+  puts indent + txt
+end
+```
 
-## Usage
+### Further reading
 
-TODO: Write usage instructions here
+* [Usage](doc/usage_examples.md): More complex examples and conventions.
+* [About interactions](doc/about_interactions.md): Motivation, when to use them.
+* [Features and design considerations](doc/features_and_design_considerations.md)
 
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+We have [instructions for releasing a new version](doc/how_to_release_new_version.md).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/makwa.
+Bug reports and pull requests are welcome on GitHub at https://github.com/animikii/makwa.
 
 ## License
 

data/doc/about_interactions.md

@@ -0,0 +1,50 @@
+# About Interactions
+
+## When to use interactions
+
+When to use an interaction:
+
+* Integration with Rails CRUD forms:
+  * FormObject preparation.
+  * FormParams sanitization/transformation
+  * special validations
+  * CRUD persistence operations
+  * post-persistence actions like sending an email, or triggering another interaction
+* Decoupling behavior from ActiveRecord classes:
+  * Replace **ALL** ActiveRecord `:after_...` callbacks with interactions. This refers to all after callbacks, not just save.
+  * Replace **MOST** ActiveRecord `:before_...` callbacks with interactions. This refers to all `:before_…` callbacks, not just save. An exception that can remain as a callback could be a `:before_validation` callback to sanitize an email address (strip surrounding whitespace, lower case), however, if there is already an interaction to create/update a user, you may as well do it in the interaction.
+  * Replace Model instance and class methods that implement complex behaviours with interactions. Note that you can still use the Model methods as interface, however, the implementation should live in an interaction.
+* Implement complex domain behaviours by composing sub tasks into higher level processes.
+* Wrap a 3rd party service so that we can swap it out in a single place if needed.
+
+## ReturningInteractions
+
+ReturningInteractions are a special kind of interaction, optimized for usage with Rails forms.
+
+### Motivation
+
+When processing a Rails form submission, e.g., via :create or :update, if the inputs are not valid (and the interaction’s input validation fails), we still need a form object that we can use to re-render the form. When an ActiveInteraction’s input validation fails, we don’t get that. We just get the errors and the interaction itself. And the interaction may not be a suitable stand-in for the model object if it does not implement all the methods found on the model object (e.g., associations or decorators).
+
+This is where ReturningInteractions come into play. Instead of returning themselves when errors exist, they will always return the specified input value. And any errors are merged into the returned value. The convention is to use the ActiveRecord instance as returned input value. Then, if errors exist, the returned instance can be used as form object to re-render the form.
+
+### How they are different from regular interactions
+
+ReturningInteractions inherit from ActiveInteraction, however, they are different in the following ways:
+
+* They will always return the specified input, no matter what happens after you invoke them:
+  * If input validations fail, and the `#execute_returning` method is never reached.
+  * If associated ActiveModel validations fail.
+  * If exceptions are rescued.
+  * If the `#execute_returning` method returns early.
+  * If it follows the happy path, everything goes as expected, independently of what the `#execute_returning` method returns.
+* They merge any errors added to the returned input argument before returning it.
+* They inherit from ReturningInteraction.
+* They have an additional returning macro to specify which one of the inputs is guaranteed to be returned.
+* The `#execute` method is replaced with `#execute_returning`.
+
+### Additional notes
+
+* They require the returned input argument to implement the ActiveModel::Errors interface so that any errors can be merged.
+* They behave very similar to the Ruby `#tap` method.
+* Instead of an ActiveRecord instance, you can also pass the record’s id to a ReturningInteraction. This is possible thanks to ActiveInteraction’s record input filter type.
+* Convention for input arguments: Don’t nest object attrs in a hash since ActiveInteraction doesn’t have good input filter error reporting on nested values. It’s better to have all attrs as flat list, merged with the returned record. (NOTE: This may be addressed with ActiveInteraction v5)

data/doc/features_and_design_considerations.md

@@ -0,0 +1,95 @@
+# Features and design considerations
+
+## Input validation and coercion
+
+All input arguments are validated and coerced before the interaction is invoked. Depending on the use case we can use the following validations:
+
+* ActiveInteraction input filters - Check for presence of input argument keys, their types, and can set default values for optional input arguments.
+* ActiveModel validations in the Interaction. - Use the full power of ActiveModel::Validation to check for specific values, or higher level business rules that are specific to the interaction.
+* ActiveModel validations in the ActiveRecord instance passed to a ReturningInteraction - For shared validations that apply to all related interactions.
+* Dry-validation based contracts for advanced validations of deeply nested data structures.
+
+The validation solutions listed above offer the following features:
+
+* Type checking.
+* Ability to implement complex validation rules.
+* Ability to look at other input args when validating an arg.
+* Composability: Input validations can be composed to prevent duplication and allow re-use. Dry validation offers this temporary workaround for composing rules: https://github.com/dry-rb/dry-validation/issues/593#issuecomment-631597226
+* Type coercion, e.g., for Rails request params that need to be cast from String to Integer.
+* Runtime validation (since we don’t know what arguments are passed to an Interaction at compile time).
+* Default values can be assigned when using ActiveInteraction input filters.
+
+Below are some options for input argument validation:
+
+* ActiveModel Validations: https://api.rubyonrails.org/classes/ActiveModel/Validations.html
+* ActiveInteraction filters: https://github.com/AaronLasseigne/active_interaction#filters
+* dry-validation contracts: https://dry-rb.org/gems/dry-validation/
+
+## Composability
+
+Interactions can be composed to facilitate re-use and modularity.
+
+* Errors raised in composed interactions are merged into the parent interaction.
+* Execution in parent interaction stops when a composed interaction fails.
+* Composed interactions act like the #run! bang method with exception handling built in.
+
+Code example:
+
+```
+def execute
+  r1 = compose(Nested::Service1, arg1: 123, arg2: "a string")
+  r2 = compose(Nested::Service2, arg1: r1)
+end
+```
+
+Note that ActiveInteraction input filters can also be reused via `import_filters OtherInteraction`.
+
+## Exception handling and error reporting
+
+* Errors (not Ruby Exceptions!) added in an interaction are accessible to the caller for testing and notification purposes.
+* Errors are addable manually inside the interaction via errors.add(:base, text: "something went wrong", key: :something_went_wrong).
+* Errors are mergeable from other sources, e.g., ActiveRecord objects or nested interactions via errors.merge!(@user.errors).
+* Early exit of the interaction is possible if an unrecoverable error condition is detected. E.g., via return_if_errors! or return.
+
+## Localization
+
+Success and error messages are customizable via Rails' default I18n mechanisms.
+
+## Integration with Rails forms
+
+ReturningInteractions, are a specialized subclass of ActiveInteraction, work well with processing params submitted from Rails forms, and with possible re-rendering of the form if there are any errors.
+
+## Dependency injection
+
+Dependencies can be injected into an interaction, mostly for testing. Example: We inject a fake `Git` library when testing code that makes git commits. Other examples: `File`, `Time`, `TwitterApi`, etc.
+
+## Serializability
+
+Invocation of an interaction, with its input arguments, can be serialized in a simple, robust, and performant way. We accomplish this by limiting input arguments to basic Ruby types: Hashes, Arrays, Strings, Numbers, and Booleans.
+
+## Logging
+
+Interactions print detailed info to the log. Output includes:
+
+* Name of invoked interaction
+* caller
+* input args
+* any errors
+
+Example:
+
+```
+Executing interaction Niiwin::NwLoader::InitialLoad (id#70361484811280)
+ ↳ inputs: {} (id#70361484811280)
+    Executing interaction Niiwin::NwLoader::NwConfigs::Load (id#70361484766000)
+     ↳ called from niiwin/nw_loader/initial_load.rb:14:in `initial_load_nw_config' (id#70361484766000)
+     ↳ inputs: {} (id#70361484766000)
+     ↳ outcome: succeeded (id#70361484766000)
+    Executing interaction Niiwin::NwLoader::NwConfigs::Validate (id#70361476717620)
+     ↳ called from niiwin/nw_loader/initial_load.rb:15:in `initial_load_nw_config' (id#70361476717620)
+     ↳ inputs: {} (id#70361476717620)
+     ↳ outcome: succeeded (id#70361476717620)
+ ↳ outcome: succeeded (id#70361484811280)
+```
+
+You can turn off logging by overriding the `ApplicationInteraction#debug` method.

data/doc/how_to_release_new_version.md

@@ -5,10 +5,10 @@
   * Update CHANGELOG.md
   * Commit changes
 * Prepare new release
-  * Bump version via one of
-    * `gem bump --tag --version major`
-    * `gem bump --tag --version minor`
-    * `gem bump --tag --version patch`
-  * The bump command will commit the new version and tag the commit.
+  * Assign new version in `lib/makwa/version.rb`
+  * Commit the change with "Bump makwa to <version>"
+  * Tag the commit of the new version with `v<version>`
+  * Push the changes
+  * Build the gem with `gem build`
 * Distribute new release
-  * `gem release` - This will push the new release to rubygems.org.
+  * `gem push makwa-<version>.gem` - This will push the new release to rubygems.org.

data/doc/usage_examples.md

@@ -0,0 +1,222 @@
+# Makwa Interaction Usage Examples
+
+## Specify your Application interactions
+
+All specific interactions will inherit from your app-wide interactions:
+
+```ruby
+# app/interactions/application_interaction.rb
+class ApplicationInteraction < Makwa::Interaction
+  def debug(txt)
+    # Uncomment the next line for detailed debug output
+    # puts indent + txt
+  end
+end
+```
+
+```ruby
+# app/interactions/application_returning_interaction.rb
+class ApplicationReturningInteraction < Makwa::ReturningInteraction
+  def debug(txt)
+    # Uncomment the next line for detailed debug output
+    # puts indent + txt
+  end
+end
+```
+
+## Implement a regular interaction to wrap a 3rd party service
+
+This example interaction wraps an email sending service:
+
+```ruby
+# app/interactions/infrastructure/send_email.rb
+module Infrastructure
+  class SendEmail < ApplicationInteraction
+    string :recipient_email
+    string :subject
+    string :body
+
+    validates :recipient_email, presence: true, format: {with: /.+@.+/}
+    validates :subject, presence: true
+
+    def execute
+      ThirdPartyEmailService.send(
+        to: recipient_email,
+        subject: subject,
+        body: body
+      )
+    end
+  end
+end
+```
+
+You can then use this interaction to send emails:
+
+```ruby
+Infrastructure::SendEmail.run!(recipient_email: "email@test.com", subject: "Email Subject", body: "Email Body")
+```
+
+## Implement a ReturningInteraction to create a user
+
+```ruby
+# app/users/create.rb
+module Users
+  class Create < ApplicationReturningInteraction
+    returning :user
+
+    string :first_name
+    string :last_name
+    string :email
+    record :user
+
+    validates :first_name, presence: true
+    validates :last_name, presence: true
+    validates :email, presence: true, format: {with: /.+@.+/}
+
+    def execute_returning
+      user.update(inputs.except(:user))
+      return_if_errors!
+
+      compose(
+        Infrastructure::SendEmail, # See the example above for details
+        recipient_email: user.email,
+        subject: "Welcome to Makwa",
+        body: "Lorem ipsum..."
+      )
+    end
+  end
+end
+```
+
+Use this interaction from the controller:
+
+```ruby
+# app/controllers/users_controller.rb
+class UsersController < ApplicationController
+  def new
+    @user = User.new
+  end
+
+  def create
+    # Differences: Pass in the `:user` input and call `#run_returning!` instead of `#run`.
+    @user = Users::Create.run_returning!(
+      {user: User.new}.merge(params.fetch(:user, {}))
+    )
+
+    if @user.errors_empty?
+      redirect_to(@user)
+    else
+      render(:edit)
+    end
+  end
+end
+```
+
+## Implement a ReturningInteraction to update a user
+
+```ruby
+# app/users/update.rb
+module Users
+  class Update < ApplicationReturningInteraction
+    returning :user
+
+    string :first_name
+    string :last_name
+    string :email
+    record :user
+
+    validates :first_name, presence: true
+    validates :last_name, presence: true
+    validates :email, presence: true, format: {with: /.+@.+/}
+
+    def execute_returning
+      user.update(inputs.except(:user))
+    end
+  end
+end
+```
+
+Use this interaction from the controller:
+
+```ruby
+# app/controllers/users_controller.rb
+class UsersController < ApplicationController
+  before_action :load_user
+
+  def edit
+  end
+
+  def update
+    @user = Users::Update.run_returning!(
+      {user: @user}.merge(params.fetch(:user, {}))
+    )
+
+    if @user.errors_empty?
+      redirect_to(@user)
+    else
+      render(:edit)
+    end
+  end
+end
+```
+
+## Usage conventions
+
+Interactions follow these conventions:
+
+* **Code location**: Interactions are stored in app/interactions.
+* **Naming**: Interaction names always start with a verb, optionally followed by an Object noun. The Interaction’s parent namespaces provide additional context. When referring to ActiveRecord models in an interaction’s parent namespace, use plural form. This is to avoid naming conflicts with ActiveRecord models. Examples:
+  * `users/create.rb`
+  * `facilitator/groups/close.rb`
+  * `nw_app_structure/nw_patch_items/nw_tables/change/prepare_form_object.rb`
+* **Inheritance**: Interactions inherit from ApplicationInteraction, ApplicationReturningInteraction, or one of their descendants.
+* **Invocation**: You can invoke an Interaction in one of the following ways:
+  * `.run` - always returns the Interaction outcome. You can then query the outcome with `#errors_empy?`, `#errors_any?`, `#result` and `#errors`. This is the primary way of invoking Interactions. Example: `outcome = NwAppStructure::NwPatches::Apply.run(id: "1234abcd")`
+  * `.run!` - the bang version returns the Interaction’s return value if successful, and raises an exception if not successful. This can be used as a convenience method where we want to assure that the interaction executes successfully, and where we want easy access to the return value.
+  * **ReturningInteractions** can only be invoked with `.run_returning!`.
+* **Input param safety**: Interactions validate, restrict, and coerce their input args. That means you don't need strong params. You can use raw controller params via `user_params: params.to_unsafe_h[:user]`.
+* **Error handling**:
+  * Rely on ActiveModel validations to add errors to the interaction.
+  * Use `errors.add` and `errors.merge!` to manually add errors to an interaction.
+  * When composing interactions, errors in nested interactions bubble to the top.
+  * Errors can be used for flow control, e.g., via `#return_if_errors!`.
+* **Outcome**: Regular interactions that are invoked with `.run` return an outcome:
+  * Outcome can be tested for presence/absence of any errors. Please use `#errors_empty?` and `#errors_any?` instead of `#valid?`. See caveat below related to `#valid?` for details.
+  * Outcome has a `#result` (return value of the #execute method).
+  * Outcome exposes any errors via an `ActiveModel::Errors` compatible API.
+* **Input arguments**:
+  * Input arguments to an interaction are always wrapped in a Hash. The hash keys correspond to the interaction’s input filters.
+  * As a general guideline, interactions receive the same types of arguments as the corresponding controller action would expect as `params`: Only basic Ruby data types like Hashes, Arrays, Strings, Numbers, Dates, Times, etc. This convention provides the following benefits:
+    * Provides the simplest API possible.
+    * Makes it easy to invoke an Interaction from a controller action: Just forward the params as is.
+    * Makes it easy to invoke an interaction from the console. You can type all input args as literals.
+    * Makes it easy to pass test data into an interaction.
+    * Makes it easy to serialize the invocation of an interaction, e.g., for a Sidekiq background job.
+    * We do not pass in ActiveRecord instances, but their ids instead. We rely on ActiveRecord caching to prevent multiple DB reads when passing the same record id into nested interactions. Exceptions:
+      * You can pass a descendant of ActiveModel, e.g., an ActiveRecord instance as the returned input to a ReturningInteraction. Use the record input filter type. It accepts both the ActiveRecord instance, as well as its id attribute. That way, you can still pass in basic Ruby types, e.g., in the console when invoking the interaction.
+      * In some use cases with nested interactions, we may choose to pass in an ActiveRecord instance to work around persistence concerns.
+  * When an interaction is concerned with an ActiveRecord instance, we pass the record’s id under the :id hash key (unless it’s a ReturningInteraction).
+
+## Caveat: Don’t use #valid?
+
+We need to address the issue where the supposedly non-destructive ActiveModel method `#valid?` is actually destructive. This affects both ActiveModel::Validations as well as ActiveInteraction. The `#valid?` method actually clears out any existing errors and re-runs ActiveModel validations. This causes any errors added outside of an ActiveModel::Validation to disappear, resulting in `#valid?` returning true when it shouldn’t.
+
+Don't use `#valid?`, use `#errors_empty?` instead.
+
+Don't use `#invalid?`, use `#errors_any?` instead.
+
+Rails source code at activemodel/lib/active_model/validations.rb, line 334:
+
+```ruby
+def valid?(context = nil)
+  current_context, self.validation_context = validation_context, context
+  errors.clear
+  run_validations!
+ensure
+  self.validation_context = current_context
+end
+```
+
+The official Rails way to circumvent the clearing of errors is to use errors.any? or errors.empty?
+
+We wrap this implementation detail (calling errors.any?) in a method that clearly communicates intent, prevents well intentioned devs from changing `#errors.empty?` to `#valid?`, and helps us audit code to make sure that we're not using the default `#valid?` method in connection with Interactions (Both on the interaction itself, and on any ActiveRecord instances it touches).

data/lib/makwa/interaction.rb

@@ -28,7 +28,7 @@ module Makwa
     #
 
     # Log execution of interaction, caller, and inputs
-    set_callback :type_check, :before, ->(interaction) {
+    set_callback :filter, :before, ->(interaction) {
       debug("Executing interaction #{interaction.class.name} #{interaction.id_marker}")
       calling_interaction = interaction.calling_interaction
       debug(" ↳ called from #{calling_interaction} #{interaction.id_marker}") if calling_interaction.present?
@@ -41,10 +41,10 @@ module Makwa
     # Log interaction's outcome and errors if any.
     set_callback :execute, :after, ->(interaction) {
       if interaction.errors_empty?
-        debug(" ↳ outcome: succeeded (id##{interaction.object_id})")
+        debug(" ↳ outcome: succeeded #{interaction.id_marker}")
       else
-        debug(" ↳ outcome: failed (id##{interaction.object_id})")
-        debug(" ↳ errors: #{interaction.errors.details} (id##{interaction.object_id})")
+        debug(" ↳ outcome: failed #{interaction.id_marker}")
+        debug(" ↳ errors: #{interaction.errors.details} #{interaction.id_marker}")
       end
     }
 

data/lib/makwa/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Makwa
-  VERSION = "0.2.1"
+  VERSION = "1.0.1"
 end

data/makwa.gemspec

@@ -15,7 +15,7 @@ Gem::Specification.new do |spec|
   spec.summary = "Interactions for Ruby on Rails apps."
   spec.homepage = "https://github.com/animikii/makwa"
   spec.license = "MIT"
-  spec.required_ruby_version = ">= 2.4.0"
+  spec.required_ruby_version = ">= 2.7.0"
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/animikii/makwa"
@@ -28,7 +28,7 @@ Gem::Specification.new do |spec|
   end
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "active_interaction", "~> 4.0"
+  spec.add_dependency "active_interaction", "~> 5.2.0"
 
   spec.add_development_dependency "standard"
   spec.add_development_dependency "byebug"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: makwa
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 1.0.1
 platform: ruby
 authors:
 - Jo Hund
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-11-03 00:00:00.000000000 Z
+date: 2022-12-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: active_interaction
@@ -17,14 +17,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: 5.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: 5.2.0
 - !ruby/object:Gem::Dependency
   name: standard
   requirement: !ruby/object:Gem::Requirement
@@ -69,7 +69,10 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- doc/about_interactions.md
+- doc/features_and_design_considerations.md
 - doc/how_to_release_new_version.md
+- doc/usage_examples.md
 - lib/makwa.rb
 - lib/makwa/interaction.rb
 - lib/makwa/returning_interaction.rb
@@ -90,14 +93,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.4.0
+      version: 2.7.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.1.6
 signing_key: 
 specification_version: 4
 summary: Interactions for Ruby on Rails apps.