makwa 1.0.0 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b5b57daebaedd9cdfe6e14503bc559f2b3cc9dc40beeb3461c2070b1f2c659a1
-  data.tar.gz: 1f57dc2aa9f5376a14ae4bde76d88be11ba6ad897892f8adeb69272962426116
+  metadata.gz: 347d964215a73774af300989657a8b00cc8ca7cfc33ef3574fc27ab9b2a2b70e
+  data.tar.gz: 509297308f4826aae87b1ebe4b5d1bc0b92c481e0a32b8835fc90bf4c7691632
 SHA512:
-  metadata.gz: 41aa06f6e10421a0c1fe9af084b36838670c1300f00bb359975482539537f0bf852903a28cb058a0ea8ee996bcb953f850ccc915a8ac99861aa2a74e11860182
-  data.tar.gz: 76f38892c52dbeec20840416e10196c702e34ad351c2fd7f366c1d43aad4b2eb21221fc8ff113a793a4f83716c8703bfe18e9be751e36774003f655f0c2e0b8a
+  metadata.gz: 2cbfa68e12c36034d16cc25f60150b165fdb8cc43d45eadbbd7ecf8be4d3d60d8254832e62ce5c6a93132fb83fa7aec2b5f413a87b0b56e147fb777abb037f03
+  data.tar.gz: 7f9252de4f2b153d4a06369491615cf02b247666438f49047f80700a2237c40ed5f743aa4e8eabe452426e1de3ebe7d74b108a41bf9dc4695fd587bd36dc34ce

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+## [1.0.2] - 2025-01-05
+
+- Updates #return_if_errors! to not include errors in exception object. This addresses an issue where errors
+  are duplicated under the base key.
+- Adds tests for failing composed interactions.
+
+## [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.

data/doc/about_interactions.md

@@ -4,10 +4,18 @@
 
 When to use an interaction:
 
-* Use interactions for all but the most trivial ActiveRecord mutating CRUD operations.
-* 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.
+* 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
 

data/doc/features_and_design_considerations.md

@@ -1,3 +1,95 @@
 # Features and design considerations
 
-TBD
+## 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

@@ -9,5 +9,6 @@
   * 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 push makwa` - 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

@@ -15,7 +15,7 @@ end
 ```
 
 ```ruby
-# app/interactions/application_interaction.rb
+# app/interactions/application_returning_interaction.rb
 class ApplicationReturningInteraction < Makwa::ReturningInteraction
   def debug(txt)
     # Uncomment the next line for detailed debug output
@@ -50,6 +50,12 @@ module Infrastructure
 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
@@ -141,7 +147,7 @@ class UsersController < ApplicationController
   end
 
   def update
-    @user = Users::Create.run_returning!(
+    @user = Users::Update.run_returning!(
       {user: @user}.merge(params.fetch(:user, {}))
     )
 
@@ -187,7 +193,7 @@ Interactions follow these conventions:
     * 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 descendent 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.
+      * 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).
 

data/lib/makwa/interaction.rb

@@ -2,7 +2,7 @@
 
 module Makwa
   class Interaction < ::ActiveInteraction::Base
-    class Interrupt < Object.const_get(:"::ActiveInteraction::Interrupt")
+    class Interrupt < Object.const_get("::ActiveInteraction::Interrupt")
     end
 
     #
@@ -20,7 +20,7 @@ module Makwa
 
     # Exits early if there are any errors.
     def return_if_errors!
-      raise(Interrupt, errors) if errors_any?
+      raise(Interrupt, ActiveInteraction::Errors.new(self)) if errors_any?
     end
 
     #
@@ -51,7 +51,10 @@ module Makwa
     # @return [Array<String>] the callstack containing interactions only, starting with the immediate caller.
     def calling_interactions
       @calling_interactions ||= caller.find_all { |e|
-        e.index("/app/interactions/") && !e.index(__FILE__) && !e.index("/returning_interaction.rb")
+        e.index("/app/interactions/") \
+          && !e.index(__FILE__) \
+          && !e.index("/returning_interaction.rb") \
+          && !e.index("`debug'")
       }
     end
 

data/lib/makwa/returning_interaction.rb

@@ -88,7 +88,7 @@ module Makwa
 
       @_interaction_result
     rescue NotImplementedError
-      super(other, *args)
+      super
     end
   end
 end

data/lib/makwa/version.rb

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

data/makwa.gemspec

@@ -28,7 +28,7 @@ Gem::Specification.new do |spec|
   end
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "active_interaction", "~> 5.2.0"
+  spec.add_dependency "active_interaction", "~> 5.4.0"
 
   spec.add_development_dependency "standard"
   spec.add_development_dependency "byebug"

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: makwa
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.2
 platform: ruby
 authors:
 - Jo Hund
 - Fabio Papa
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-11-28 00:00:00.000000000 Z
+date: 2025-01-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: active_interaction
@@ -17,14 +17,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 5.2.0
+        version: 5.4.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 5.2.0
+        version: 5.4.0
 - !ruby/object:Gem::Dependency
   name: standard
   requirement: !ruby/object:Gem::Requirement
@@ -53,7 +53,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: 
+description:
 email:
 - jo@animikii.com
 - fabio.papa@animikii.com
@@ -85,7 +85,7 @@ metadata:
   homepage_uri: https://github.com/animikii/makwa
   source_code_uri: https://github.com/animikii/makwa
   changelog_uri: https://github.com/animikii/makwa/CHANGELOG.md
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -100,8 +100,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
-signing_key: 
+rubygems_version: 3.4.20
+signing_key:
 specification_version: 4
 summary: Interactions for Ruby on Rails apps.
 test_files: []