makwa 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b5b57daebaedd9cdfe6e14503bc559f2b3cc9dc40beeb3461c2070b1f2c659a1
-  data.tar.gz: 1f57dc2aa9f5376a14ae4bde76d88be11ba6ad897892f8adeb69272962426116
+  metadata.gz: 05d88c5995c722bae7c3769dfafe68dcf56389462b9d0ae6dc1a1fb330bab923
+  data.tar.gz: 6cb8f9358894fa15ab384a760a07bc37a1e6ac2c14dc72286421024b4fd5fb6d
 SHA512:
-  metadata.gz: 41aa06f6e10421a0c1fe9af084b36838670c1300f00bb359975482539537f0bf852903a28cb058a0ea8ee996bcb953f850ccc915a8ac99861aa2a74e11860182
-  data.tar.gz: 76f38892c52dbeec20840416e10196c702e34ad351c2fd7f366c1d43aad4b2eb21221fc8ff113a793a4f83716c8703bfe18e9be751e36774003f655f0c2e0b8a
+  metadata.gz: 7a5426ce17f47958382bcd42cb203524e2625c9fe67a3f1b3cb3afc371592bc1ca11b4fd8db705d2710bf0c7b75202b762ec8f272d0f3cd5d234581e9c0e63e9
+  data.tar.gz: d71ba78909dd101447aa104d62eb49444c09713bcde3403969ad45a5b566ce10f0da4d7031c53d9aa546cbe1b3f33de6115e060f4a9663b6960e952bc4393d99

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [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.

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
 
     #

data/lib/makwa/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: makwa
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Jo Hund
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-11-28 00:00:00.000000000 Z
+date: 2022-12-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: active_interaction