interactify 0.1.0.pre.alpha.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7bbf811a8d9e44f85d4e0c5b36f4ad3291cbc8f5aa52e5d2dd31ecbdd753a256
+  data.tar.gz: 92ed7413e2ea370d388c43d9993928652d9bc23a3139d3fa083050243bc30695
+SHA512:
+  metadata.gz: 1d9e01fc12b9b02bdc9d897b81866c7d668f94cf0fafd51e018cded3ec2892d5452848000672a9c4ac139f1c1dc3d30aa23e1c16b0dcaf66afd901c4586d8eae
+  data.tar.gz: b33dc94b10b26cf1b4baeace46168641d88121bf05fe2a4c8c37098d3b5bc678667e0ff253f620def1798846b9b95533f943ef4c80726abe08a1a41662c338c0

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2023-12-16
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Mark Burns
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,363 @@
+# Interactify
+
+Interactors are a great way to encapsulate business logic in a Rails application. 
+However, sometimes in complex interactor chains, the complex debugging happens at one level up from your easy to read and test interactors.
+
+Interactify wraps the interactor and interactor-contract gem and provides additional functionality making chaining and understanding interactor chains easier.
+
+### Syntactic Sugar
+
+```ruby
+# before
+
+class LoadOrder
+  include Interactor
+  include Interactor::Contracts
+
+  expects do
+    required(:id).filled
+  end
+
+  promises do
+    required(:order).filled
+  end
+
+
+  def call
+    context.order = Order.find(context.id)
+  end
+end
+```
+
+
+```ruby
+# after
+class LoadOrder
+  include Interactify
+
+  expect :id
+  promise :order
+
+  def call
+    context.order = Order.find(id)
+  end
+end
+```
+
+
+### Lambdas
+
+With vanilla interactors, it's not possible to use lambdas in organizers, and sometimes we only want a lambda.
+So we added support.
+
+```ruby
+organize LoadOrder, ->(context) { context.order = context.order.decorate }
+
+organize \
+  Thing1, 
+  ->(c){ byebug if c.order.nil? },
+  Thing2
+```
+
+### Each/Iteration
+
+Sometimes we want an interactor for each item in a collection.
+But it gets unwieldy. 
+It was complex procedural code and is now broken into neat SRP classes (Single Responsibility Principle). 
+But there is still boilerplate and jumping around between files to follow the orchestration.
+It's easy to get lost in the orchestration code that occurs across say 7 or 8 files.
+
+So the complexity problem is just moved to the gaps between the classes and files.
+We gain things like `EachOrder`, or `EachProduct` interactors.
+
+Less obvious, still there.
+
+By using `Interactify.each` we can keep the orchestration code in one place.
+We get slightly more complex organizers, but a simpler mental model of organizer as orchestrator and SRP interactors.
+
+```ruby
+# before
+class OuterOrganizer
+  # ... boilerplate ...
+  organize SetupStep, LoadOrders, DoSomethingWithOrders
+end
+
+class LoadOrders
+  # ... boilerplate ...
+  def call
+    context.orders = context.ids.map do |id|
+      LoadOrder.call(id: id).order
+    end
+  end
+end
+
+class LoadOrder
+  # ... boilerplate ...
+  def call
+    # ...
+  end
+end
+
+class DoSomethingWithOrders
+  # ... boilerplate ...
+  def call
+    context.orders.each do |order|
+      DoSomethingWithOrder.call(order: order)
+    end
+  end
+end
+
+class DoSomethingWithOrder
+  # ... boilerplate ...
+  def call
+    # ...
+  end
+end
+```
+
+
+```ruby
+# after
+class OuterOrganizer
+  # ... boilerplate ...
+  organize \
+    SetupStep,
+    self.each(:ids, 
+      LoadOrder, 
+      ->(c){ byebug if c.order.nil? },
+      DoSomethingWithOrder
+    )
+end
+
+class LoadOrder
+  # ... boilerplate ...
+  def call
+    # ...
+  end
+end
+
+
+class DoSomethingWithOrder
+  # ... boilerplate ...
+  def call
+    # ...
+  end
+end
+```
+
+### Conditionals (if/else)
+
+Along the same lines of each/iteration. We sometimes have to 'break the chain' with interactors just to conditionally call one interactor chain path or another.
+
+The same mental model problem applies. We have to jump around between files to follow the orchestration.
+
+```ruby
+# before
+class OuterThing
+  # ... boilerplate ...
+  organize SetupStep, InnerThing
+end
+
+class InnerThing
+  # ... boilerplate ...
+  def call
+    if context.thing == 'a'
+      DoThingA.call(context)
+    else
+      DoThingB.call(context)
+    end
+  end
+end
+```
+
+
+```ruby
+# after
+class OuterThing
+  # ... boilerplate ...
+  organize \
+    SetupStep,
+    self.if(->(c){ c.thing == 'a' }, DoThingA, DoThingB),
+end
+
+```
+
+### More Conditionals 
+
+```ruby
+class OuterThing
+  # ... boilerplate ...
+  organize \
+    self.if(:key_set_on_context, DoThingA, DoThingB),
+    AfterBothCases
+end
+```
+
+### Simple chains
+Sometimes you want an organizer that just calls a few interactors in a row.
+You may want to create these dynamically at load time, or you may just want to keep the orchestration in one place.
+
+`self.chain` is a simple way to do this.
+
+```ruby
+class SomeOrganizer
+  include Interactify
+
+  organize \
+    self.if(:key_set_on_context, self.chain(DoThingA, ThenB, ThenC), DoDifferentThingB),
+    EitherWayDoThis
+end
+
+```
+
+### Sidekiq Jobs
+Sometimes you want to asyncify an interactor.
+
+```ruby
+# before
+class SomeInteractor
+  include Interactify
+
+  def call
+    # ...
+  end
+end
+
+clsas SomeInteractorJob
+  include Sidekiq::Job
+
+  def perform(*args)
+    SomeInteractor.call(*args)
+  end
+end
+
+SomeInteractor.call(*args)
+code is changed to
+SomeInteractorJob.perform_async(*args)
+```
+
+```ruby
+# after
+class SomeInteractor
+  include Interactify
+
+  def call
+    # ...
+  end
+end
+
+# no need to manually create a job class or handle the perform/call impedance mismatch
+SomeInteractor::Async.call(*args)
+
+# This also makes it easy to add cron jobs to run interactors. As any interactor can be asyncified.
+# By using it's internal Async class.
+```
+
+## FAQs
+- This is ugly isn't it?
+
+```ruby
+class OuterOrganizer
+  # ... boilerplate ...
+  organize \
+    SetupStep,
+    self.each(:ids, 
+      LoadOrder, 
+      ->(c){ byebug if c.order.nil? },
+      DoSomethingWithOrder
+    )
+end
+```
+
+Yes I agree. It's early days and I'm open to syntax improvement ideas. This is really about it being conceptually less ugly than the alternative, which is to jump around between lots of files. In the existing alternative to using this gem the ugliness is not within each individual file, but within the overall hidden architecture and the hunting process of jumping around in complex interactor chains. We can't see that ugliness but we probably experience it. If you don't feel or experience that ugliness then this gem may not be the right fit for you.
+
+
+- Is this interactor/interactor-contracts compatible? 
+Yes and we use them as dependencies. It's possible we'd drop those dependencies in the future but unlikely. I think it's highly likely we'd retain compatibility.
+
+
+- Why not propose changes to the interactor or interactor-contracts gem?
+Honestly, I think both are great and why we've built on top of them. 
+I presume they'd object to such an extensive opinionated change, and I think that would be the right decision too.
+If this becomes more stable, less coupled to Rails, there's interest, and things we can provide upstream I'd be happy to propose changes to those gems.
+
+- Isn't this all just syntactic sugar?
+Yes, but it's sugar that makes the code easier to read and understand.
+
+- Is it really easier to parse this new DSL/syntax than POROs?
+That's subjective, but I think so. The benefit is you have fewer extraneous files patching over a common problem in interactors.
+
+- But it gets really verbose and complex!
+Again this is subjective, but if you've worked with apps with hundred or thousands of interactors, you'll have encountered these problems.
+I think when we work with interactors we're in one of two modes. 
+Hunting to find the interactor we need to change, or working on the interactor we need to change.
+This makes the first step much easier. 
+The second step has always been a great experience with interactors.
+
+- I prefer Service Objects
+If you're not heavily invested into interactors this may not be for you.
+I love the chaining interactors provide. 
+I love the contracts. 
+I love the simplicity of the interface.
+I love the way they can be composed. 
+I love the way they can be tested.
+When I've used service objects, I've found them to be more complex to test and compose.
+I can't see a clean way that using service objects to compose interactors could work well without losing some of the aforementioned benefits.
+
+### TODO
+We want to add support for explicitly specifying promises in organizers. The benefit here is on clarifying the contract between organizers and interactors.
+A writer of an organizer may expect LoadOrder to promise :order, but for the reader, it's not quite as explicit.
+The expected syntax will be
+
+```ruby
+organize \
+  LoadOrder.promising(:order), 
+  TakePayment.promising(:payment_transaction)
+```
+
+This will be validated at test time against the interactors promises.
+
+## Installation
+
+TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+
+## Usage
+
+```ruby
+# e.g. in spec/supoort/interactify.rb
+require 'interactify/rspec/matchers'
+
+Interactify.configure do |config|
+  config.root = Rails.root '/app'
+end
+
+Interactify.on_contract_breach do |context, attrs|
+  # maybe add context to Sentry or Honeybadger etc here
+end
+
+Interactify.before_raise do |exception|
+  # maybe add context to Sentry or Honeybadger etc here
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. 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).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/interactify.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/interactify/call_wrapper.rb

@@ -0,0 +1,15 @@
+module Interactify
+  module CallWrapper
+    # https://github.com/collectiveidea/interactor/blob/57b2af9a5a5afeb2c01059c40b792485cc21b052/lib/interactor.rb#L114
+    # Interactor#run calls Interactor#run!
+    # https://github.com/collectiveidea/interactor/blob/57b2af9a5a5afeb2c01059c40b792485cc21b052/lib/interactor.rb#L49
+    # Interactor.call calls Interactor.run
+    #
+    # The non bang methods call the bang methods and rescue
+    def run
+      @_interactor_called_by_non_bang_method = true
+
+      super
+    end
+  end
+end

data/lib/interactify/contract_helpers.rb

@@ -0,0 +1,71 @@
+require 'interactify/jobable'
+require 'interactify/call_wrapper'
+require 'interactify/organizer_call_monkey_patch'
+
+module Interactify
+  module ContractHelpers
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def expect(*attrs, filled: true)
+        expects do
+          attrs.each do |attr|
+            field = required(attr)
+            field.filled if filled
+          end
+        end
+
+        delegate(*attrs, to: :context)
+      end
+
+      def optional(*attrs)
+        @optional_attrs ||= []
+        @optional_attrs += attrs
+
+        delegate(*attrs, to: :context)
+      end
+
+      attr_reader :optional_attrs
+
+      def promise(*attrs, filled: true, should_delegate: true)
+        promises do
+          attrs.each do |attr|
+            field = required(attr)
+            field.filled if filled
+          end
+        end
+
+        delegate(*attrs, to: :context) if should_delegate
+      end
+    end
+
+    class ContractFailure < ::Interactor::Failure
+    end
+
+    included do
+      c = Class.new(ContractFailure)
+      # example self is Shopkeeper::Fetch
+      # failure class:  Shopkeeper::Fetch::InteractorContractFailure
+      const_set 'InteractorContractFailure', c
+      prepend CallWrapper
+      include OrganizerCallMonkeyPatch if ancestors.include? Interactor::Organizer
+
+      on_breach do |breaches|
+        breaches = breaches.map { |b| { b.property => b.messages } }.inject(&:merge)
+
+        Interactify.trigger_contract_breach_hook(context, breaches)
+
+        if @_interactor_called_by_non_bang_method == true
+          context.fail! contract_failures: breaches
+        else
+          # e.g. raises
+          # SomeNamespace::SomeClass::ContractFailure, {whatever: 'is missing'}
+          # but also sending the context into Sentry
+          exception = c.new(breaches.to_json)
+          Interactify.trigger_before_raise_hook(exception)
+          raise exception
+        end
+      end
+    end
+  end
+end

data/lib/interactify/dsl.rb

@@ -0,0 +1,67 @@
+require 'interactify/each_chain'
+require 'interactify/if_interactor'
+
+module Interactify
+  module Dsl
+    # creates a class in the attach_klass_to's namespace
+    # e.g.
+    #
+    # in Orders
+    # Interactify.each(self, :packages, A, B, C)
+    #
+    # will create a class called Orders::EachPackage, that
+    # will call the interactor chain A, B, C for each package in the context
+    def each(plural_resource_name, *each_loop_klasses)
+      EachChain.attach_klass(
+        self,
+        plural_resource_name,
+        *each_loop_klasses
+      )
+    end
+
+    def if(condition, succcess_interactor, failure_interactor = nil)
+      IfInteractor.attach_klass(
+        self,
+        condition,
+        succcess_interactor,
+        failure_interactor
+      )
+    end
+
+    # this method allows us to dynamically create
+    # an organizer from a name, and a chain of interactors
+    #
+    # e.g.
+    #
+    # Interactify.chain(:SomeClass, A, B, C, expect: [:foo, :bar])
+    #
+    # is the programmable equivalent to
+    #
+    # class SomeClass
+    #   include Interactify
+    #   organize(A, B, C)
+    # end
+    #
+    # it will attach the generate class to the currenct class and
+    # use the class name passed in
+    # rubocop:disable all
+    def chain(klass_name, *chained_klasses, expect: [])
+      expectations = expect
+
+      klass = Class.new do                             # class EvaluatingNamespace::SomeClass
+        include Interactify                            #   include Interactify
+        expect(*expectations) if expectations.any?     #   expect :foo, :bar
+
+        define_singleton_method(:source_location) do   #   def self.source_location
+          source_location                              #     [file, line]
+        end                                            #   end
+
+        organize(*chained_klasses)                     #   organize(A, B, C)
+      end                                              # end
+
+      # attach the class to the calling namespace
+      where_to_attach = self.binding.receiver
+      where_to_attach.const_set(klass_name, klass)
+    end
+  end
+end

data/lib/interactify/each_chain.rb

@@ -0,0 +1,80 @@
+module Interactify
+  class EachChain
+    attr_reader :each_loop_klasses, :plural_resource_name, :evaluating_receiver
+
+    def self.attach_klass(evaluating_receiver, plural_resource_name, *each_loop_klasses)
+      iteratable = new(each_loop_klasses, plural_resource_name, evaluating_receiver)
+      iteratable.attach_klass
+    end
+
+    def initialize(each_loop_klasses, plural_resource_name, evaluating_receiver)
+      @each_loop_klasses = each_loop_klasses
+      @plural_resource_name = plural_resource_name
+      @evaluating_receiver = evaluating_receiver
+    end
+
+    # allows us to dynamically create an interactor chain
+    # that iterates over the packages and
+    # uses the passed in each_loop_klasses
+    # rubocop:disable all
+    def klass
+      this = self
+
+      Class.new do                                                                    # class SomeNamespace::EachPackage
+        include Interactify                                          #   include Interactify
+
+        expects do                                                                    #   expects do
+          required(this.plural_resource_name)                                         #     required(:packages)
+        end                                                                           #   end
+
+        define_singleton_method(:source_location) do                                  #   def self.source_location
+          const_source_location this.evaluating_receiver.to_s                                     #     [file, line]
+        end                                                                           #   end
+
+        define_method(:run!) do                                                       #  def run!
+          context.send(this.plural_resource_name).each_with_index do |resource, index|#    context.packages.each_with_index do |package, index|
+            context[this.singular_resource_name] = resource                           #       context.package = package
+            context[this.singular_resource_index_name] = index                        #       context.package_index = index
+
+            klasses = self.class.wrap_lambdas_in_interactors(this.each_loop_klasses)
+
+            klasses.each do |interactor|                                              #       [A, B, C].each do |interactor|
+              interactor.call!(context)                                               #         interactor.call!(context)
+            end                                                                       #       end
+          end                                                                         #     end
+
+          context[this.singular_resource_name] = nil                                  #     context.package = nil
+          context[this.singular_resource_index_name] = nil                            #     context.package_index = nil
+
+          context                                                                     #     context
+        end                                                                           #   end
+
+        define_method(:inspect) do
+          "<#{this.namespace}::#{this.iterator_klass_name} iterates_over: #{this.each_loop_klasses.inspect}>"
+        end
+      end
+    end
+    # rubocop:enable all
+
+    def attach_klass
+      namespace.const_set(iterator_klass_name, klass)
+      namespace.const_get(iterator_klass_name)
+    end
+
+    def namespace
+      evaluating_receiver
+    end
+
+    def iterator_klass_name
+      :"Each#{singular_resource_name.to_s.camelize}".to_sym
+    end
+
+    def singular_resource_name
+      plural_resource_name.to_s.singularize.to_sym
+    end
+
+    def singular_resource_index_name
+      "#{singular_resource_name}_index".to_sym
+    end
+  end
+end