interactify 0.2.0.pre.alpha.1 → 0.3.0.pre.alpha.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c2dffe1928c3b1653ea12057fd660eacbef1d8fbd946d1bdbddef00494a8c8b
-  data.tar.gz: 7078fe7a6b217febd47f4598eb2e88fdcfb8affcd434dba239ee86a39a072176
+  metadata.gz: 918f4f6ae335bb5b8a748603af6a2e9d91dc11ad3d887803bbb2c7b2ba41730e
+  data.tar.gz: fe6506fe246a82d48f5a614d5c576cf74e49f38953c1d4ae98d52f1649f03aaf
 SHA512:
-  metadata.gz: 9e3eb106e5b896965c6b1fbfea135c62f4eb7f95779041c121bcb2040fd8568c54e94b4f77a3e1bcca6d922d8a8bdfcacda354d3a6396e19a49fbfce78f39af1
-  data.tar.gz: 3f998d9f35105a47becc0555ed80dff264fad2e5fe58f93ec0c731b8cab4281e457da9e3fc00d0e4709e1b62b4e2416a8a75b66f56723b610531bca8fd458ea3
+  metadata.gz: ce377154a79b527f6eaebe3258d76aadd327521abbe86847b8c9d87b5710e1782bdb02b20b3ef3661ac6dc4ee1d0c6843fdd819ccf6dda8f701e9d95063d5a9c
+  data.tar.gz: 553271645575873bc2a95968c2ff7f01a556dd24527974b6a7bb958a8eeb9f8bb66504bdace2c3736e6faac82c1a438f07d27afa85c3fdc8ac5b051cac4e20c5

data/CHANGELOG.md

@@ -1,9 +1,13 @@
 ## [Unreleased]
 
-## [0.1.0] - 2023-12-16
+## [0.1.0-alpha.1] - 2023-12-16
 
 - Initial release
 
-## [0.2.0] - 2023-12-27
+## [0.2.0-alpha.1] - 2023-12-27
 
 - Added support for Interactify.promising syntax in organizers
+
+## [0.3.0-alpha.1] - 2023-12-29
+
+- Added support for `{if: :condition, then: A, else: B}` in organizers

data/README.md

@@ -1,18 +1,9 @@
 # Interactify
 
-[Interactors](https://github.com/collectiveidea/interactor) 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.
-
-[interactor-contracts](https://github.com/michaelherold/interactor-contracts) does a fantastic job of making your interactor chains more reliable.
-
-Interactify wraps the interactor and interactor-contracts gem and provides additional functionality making chaining and understanding interactor chains easier.
-
-This is a bells and whistles gem and assumes you are working in a Rails project with Sidekiq.
-However, I'm open to the idea of making it more focused and making these more pluggable.
-
+Interactify enhances Rails applications by simplifying complex interactor chains. This gem builds on [interactors](https://github.com/collectiveidea/interactor) and [interactor-contracts](https://github.com/michaelherold/interactor-contracts) to improve readability and maintainability of business logic. It's optimized for Rails projects using Sidekiq, offering advanced features for chain management and debugging. Interactify is about making interactor usage in Rails more efficient and less error-prone, reducing the overhead of traditional interactor orchestration.
 ## Installation
 
-```Gemfile
+```ruby
 gem 'interactify'
 ```
 
@@ -39,10 +30,15 @@ end
 ```ruby
 # e.g. in spec/supoort/interactify.rb
 require 'interactify/rspec/matchers'
+
+expect(described_class).to expect_inputs(:foo, :bar, :baz)
+expect(described_class).to promise_outputs(:fee, :fi, :fo, :fum)
 ```
 
 ### Syntactic Sugar
 - Everything is an Organizer/Interactor and supports interactor-contracts.
+- They only becomes considered an organizer once `organize` is called.
+- They could technically be both (if you want?) but you have to remember to call `super` within `call` to trigger the organized interactors.
 - Concise syntax for most common scenarios with `expects` and `promises`. Verifying the presence of the keys/values.
 - Automatic delegation of expected and promised keys to the context.
 
@@ -63,7 +59,6 @@ class LoadOrder
     required(:order).filled
   end
 
-
   def call
     context.order = Order.find(context.id)
   end
@@ -89,8 +84,8 @@ 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.
+With vanilla interactors, it wasn't possible to use lambdas in organizers.
+But sometimes we only want a lambda. So we added support.
 
 ```ruby
 organize LoadOrder, ->(context) { context.order = context.order.decorate }
@@ -157,7 +152,6 @@ class DoSomethingWithOrder
 end
 ```
 
-
 ```ruby
 # after
 class OuterOrganizer
@@ -178,7 +172,6 @@ class LoadOrder
   end
 end
 
-
 class DoSomethingWithOrder
   # ... boilerplate ...
   def call
@@ -187,7 +180,7 @@ class DoSomethingWithOrder
 end
 ```
 
-### Conditionals (if/else)
+### Conditionals (if/else) with lambda
 
 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.
 
@@ -212,7 +205,6 @@ class InnerThing
 end
 ```
 
-
 ```ruby
 # after
 class OuterThing
@@ -222,9 +214,16 @@ class OuterThing
     self.if(->(c){ c.thing == 'a' }, DoThingA, DoThingB),
 end
 
+# or hash syntax
+class OuterThing
+  # ... boilerplate ...
+  organize \
+    {if: :key_set_on_context, then: DoThingA, else: DoThingB},
+    AfterBothCases
+end
 ```
 
-### More Conditionals 
+### Conditionals with a key from the context 
 
 ```ruby
 class OuterThing
@@ -348,19 +347,19 @@ class SomeInteractor
     # ...
   end
 end
-
-clsas SomeInteractorJob
-  include Sidekiq::Job
-
-  def perform(*args)
-    SomeInteractor.call(*args)
-  end
-end
 ```
 
 ```diff
--SomeInteractor.call(*args)
-+SomeInteractorJob.perform_async(*args)
+- SomeInteractor.call(*args)
++ class SomeInteractorJob
++   include Sidekiq::Job
++
++   def perform(*args)
++     SomeInteractor.call(*args)
++   end
++ end
++
++ SomeInteractorJob.perform_async(*args)
 ```
 
 ```ruby
@@ -377,8 +376,8 @@ end
 No need to manually create a job class or handle the perform/call impedance mismatch
 
 ```diff
--SomeInteractor.call!(*args)
-+SomeInteractor::Async.call!(*args)
+- SomeInteractor.call!(*args)
++ SomeInteractor::Async.call!(*args)
 ```
 
 This also makes it easy to add cron jobs to run interactors. As any interactor can be asyncified.
@@ -386,8 +385,6 @@ By using it's internal Async class.
 
 N.B. as your class is now executing asynchronously you can no longer rely on its promises later on in the chain.
 
-
-
 ## FAQs
 - This is ugly isn't it?
 
@@ -403,73 +400,33 @@ class OuterOrganizer
     )
 end
 ```
+1. Do you find the syntax of OuterOrganizer ugly?
 
-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.
+While the syntax might seem unconventional initially, its conceptual elegance lies in streamlining complex interactor chains. Traditional methods often involve navigating through multiple files, creating a hidden and cumbersome architecture. This gem aims to alleviate that by centralizing operations, making the overall process more intuitive.
 
-- 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.
+2. Is this compatible with interactor/interactor-contracts?
 
-- 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.
+Yes, it's fully compatible. We currently use these as dependencies. While there's a possibility of future changes, maintaining this compatibility is a priority.
 
-### TODO
-We want to add support for explicitly specifying promises in organizers. 
+3. Why not suggest enhancements to the interactor or interactor-contracts gems?
 
-The benefit here is on clarifying the contract between organizers and interactors.
-
-This is another variation of the "interactors themselves are great but their coordination and finding where things happen is hard in large applications".
-
-By adding promise notation to organizers, we can signal to the reader that 'here in this part of the chain is the thing you are looking for'.
-
-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)
-```
+These gems are excellent in their own right, which is why we've built upon them. Proposing such extensive changes might not align with their current philosophy. However, if our approach proves stable and garners interest, we're open to discussing potential contributions to these gems.
 
-This will be validated at test time against the interactors promises.
+4. Is this just syntactic sugar?
 
+It's more than that. This approach enhances readability and comprehension of the code. It simplifies the structure, making it easier to navigate and maintain.
 
-## Development
+5. Is the new DSL/syntax easier to understand than plain old Ruby objects (POROs)?
 
-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.
+This is subjective, but we believe it is. It reduces the need for numerous files addressing common interactor issues, thereby streamlining the workflow.
 
-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).
+6. Doesn't this approach become verbose and complex in large applications?
 
-## Contributing
+While it may appear so, this method shines in large-scale applications with numerous interactors. It simplifies locating and modifying the necessary interactors, which is often a cumbersome process.
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/interactify.
+7. What if I prefer using Service Objects?
 
+That's completely valid. Service Objects have their merits, but this gem is particularly useful for those deeply engaged with interactors. It capitalizes on the chaining, contracts, simplicity, composability, and testability that interactors offer. Combining Service Objects with interactors might not retain these advantages as effectively.
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/interactify/contract_helpers.rb

@@ -2,7 +2,7 @@
 
 require "interactify/jobable"
 require "interactify/call_wrapper"
-require "interactify/organizer_call_monkey_patch"
+require "interactify/organizer"
 require "interactify/contract_failure"
 
 module Interactify
@@ -48,7 +48,7 @@ module Interactify
       # failure class:  Whatever::SomeInteractor::InteractorContractFailure
       const_set "InteractorContractFailure", c
       prepend CallWrapper
-      include OrganizerCallMonkeyPatch if ancestors.include? Interactor::Organizer
+      include Organizer
 
       on_breach do |breaches|
         breaches = breaches.map { |b| { b.property => b.messages } }.inject(&:merge)

data/lib/interactify/dsl.rb

@@ -2,6 +2,7 @@
 
 require "interactify/each_chain"
 require "interactify/if_interactor"
+require "interactify/unique_klass_name"
 
 module Interactify
   module Dsl
@@ -63,6 +64,7 @@ module Interactify
 
       # attach the class to the calling namespace
       where_to_attach = self.binding.receiver
+      klass_name = UniqueKlassName.for(where_to_attach, klass_name)
       where_to_attach.const_set(klass_name, klass)
     end
   end

data/lib/interactify/each_chain.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "interactify/unique_klass_name"
+
 module Interactify
   class EachChain
     attr_reader :each_loop_klasses, :plural_resource_name, :evaluating_receiver
@@ -38,7 +40,7 @@ module Interactify
             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 = InteractorWrapper.wrap_many(self, this.each_loop_klasses)
 
             klasses.each do |interactor|                                              #       [A, B, C].each do |interactor|
               interactor.call!(context)                                               #         interactor.call!(context)
@@ -59,8 +61,10 @@ module Interactify
     # rubocop:enable all
 
     def attach_klass
-      namespace.const_set(iterator_klass_name, klass)
-      namespace.const_get(iterator_klass_name)
+      name = iterator_klass_name
+
+      namespace.const_set(name, klass)
+      namespace.const_get(name)
     end
 
     def namespace
@@ -68,7 +72,9 @@ module Interactify
     end
 
     def iterator_klass_name
-      :"Each#{singular_resource_name.to_s.camelize}".to_sym
+      prefix = "Each#{singular_resource_name.to_s.camelize}"
+
+      UniqueKlassName.for(namespace, prefix)
     end
 
     def singular_resource_name

data/lib/interactify/if_interactor.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "interactify/unique_klass_name"
+
 module Interactify
   class IfInteractor
     attr_reader :condition, :success_interactor, :failure_interactor, :evaluating_receiver
@@ -49,8 +51,9 @@ module Interactify
     # rubocop:enable all
 
     def attach_klass
-      namespace.const_set(if_klass_name, klass)
-      namespace.const_get(if_klass_name)
+      name = if_klass_name
+      namespace.const_set(name, klass)
+      namespace.const_get(name)
     end
 
     def namespace
@@ -58,9 +61,10 @@ module Interactify
     end
 
     def if_klass_name
-      name = condition.is_a?(Proc) ? "Proc" : condition
+      prefix = condition.is_a?(Proc) ? "Proc" : condition
+      prefix = "If#{prefix.to_s.camelize}"
 
-      "If#{name.to_s.camelize}".to_sym
+      UniqueKlassName.for(namespace, prefix)
     end
   end
 end

data/lib/interactify/interactor_wrapper.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "interactify/unique_klass_name"
+
+module Interactify
+  class InteractorWrapper
+    attr_reader :organizer, :interactor
+
+    def self.wrap_many(organizer, interactors)
+      Array(interactors).map do |interactor|
+        wrap(organizer, interactor)
+      end
+    end
+
+    def self.wrap(organizer, interactor)
+      new(organizer, interactor).wrap
+    end
+
+    def initialize(organizer, interactor)
+      @organizer = organizer
+      @interactor = interactor
+    end
+
+    def wrap
+      case interactor
+      when Hash
+        wrap_conditional
+      when Array
+        wrap_chain
+      when Proc
+        wrap_proc
+      else
+        interactor
+      end
+    end
+
+    def wrap_chain
+      return self.class.wrap(organizer, interactor.first) if interactor.length == 1
+
+      klass_name = UniqueKlassName.for(organizer, "Chained")
+      organizer.chain(klass_name, *interactor.map { self.class.wrap(organizer, _1) })
+    end
+
+    def wrap_conditional
+      raise ArgumentError, "Hash must have at least :if, and :then key" unless condition && then_do
+
+      return organizer.if(condition, then_do, else_do) if else_do
+
+      organizer.if(condition, then_do)
+    end
+
+    def condition = interactor[:if]
+    def then_do = interactor[:then]
+    def else_do = interactor[:else]
+
+    def wrap_proc
+      this = self
+
+      Class.new do
+        include Interactify
+
+        define_singleton_method :wrapped do
+          this.interactor
+        end
+
+        define_method(:call) do
+          this.interactor.call(context)
+        end
+      end
+    end
+  end
+end

data/lib/interactify/{organizer_call_monkey_patch.rb → organizer.rb}

@@ -1,32 +1,17 @@
 # frozen_string_literal: true
 
+require "interactify/interactor_wrapper"
+
 module Interactify
-  module OrganizerCallMonkeyPatch
+  module Organizer
     extend ActiveSupport::Concern
 
     class_methods do
       def organize(*interactors)
-        wrapped = wrap_lambdas_in_interactors(interactors)
+        wrapped = InteractorWrapper.wrap_many(self, interactors)
 
         super(*wrapped)
       end
-
-      def wrap_lambdas_in_interactors(interactors)
-        Array(interactors).map do |interactor|
-          case interactor
-          when Proc
-            Class.new do
-              include Interactify
-
-              define_method(:call) do
-                interactor.call(context)
-              end
-            end
-          else
-            interactor
-          end
-        end
-      end
     end
 
     def call

data/lib/interactify/unique_klass_name.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Interactify
+  module UniqueKlassName
+    def self.for(namespace, prefix)
+      id = generate_unique_id
+      klass_name = :"#{prefix}#{id}"
+
+      while namespace.const_defined?(klass_name)
+        id = generate_unique_id
+        klass_name = :"#{prefix}#{id}"
+      end
+
+      klass_name.to_sym
+    end
+
+    def self.generate_unique_id
+      rand(10_000)
+    end
+  end
+end

data/lib/interactify/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Interactify
-  VERSION = "0.2.0-alpha.1"
+  VERSION = "0.3.0-alpha.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: interactify
 version: !ruby/object:Gem::Version
-  version: 0.2.0.pre.alpha.1
+  version: 0.3.0.pre.alpha.1
 platform: ruby
 authors:
 - Mark Burns
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-12-27 00:00:00.000000000 Z
+date: 2023-12-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: interactor
@@ -127,12 +127,14 @@ files:
 - lib/interactify/interactor_wiring/constants.rb
 - lib/interactify/interactor_wiring/error_context.rb
 - lib/interactify/interactor_wiring/files.rb
+- lib/interactify/interactor_wrapper.rb
 - lib/interactify/job_maker.rb
 - lib/interactify/jobable.rb
 - lib/interactify/mismatching_promise_error.rb
-- lib/interactify/organizer_call_monkey_patch.rb
+- lib/interactify/organizer.rb
 - lib/interactify/promising.rb
 - lib/interactify/rspec/matchers.rb
+- lib/interactify/unique_klass_name.rb
 - lib/interactify/version.rb
 - sig/interactify.rbs
 homepage: https://github.com/markburns/interactify