interactify 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c0ac09f812f0ad0ef3787c8bba0088bcbf24853e77f054a2751778eb581e7ee2
-  data.tar.gz: e4cbff812c74598c1f6a846b25007ed5058e1ab89b0ad51323e49de847579291
+  metadata.gz: d55a6d70e6996f8fb4e2f523f80532b6337e43072110283c9479fb4ee3f10bde
+  data.tar.gz: a948d6aed7f5076ebcc2851f1ede6658353c64c4e4947d68b7a70d0975828a92
 SHA512:
-  metadata.gz: 8c3c740e8130e66acf52ffb1131f75de98eba440aa5183cc0d8b18390196c0b6ed28e61f0d4df17391c0956fe785bcd3f5d45a41fa65b8b567906b29a11c7fe1
-  data.tar.gz: 1ad479044c68b77f757c99a8fafd51658f99cc0d86ce947ff4ce385fbb5f32345e7cf8d0979fba2a5ddf70d2feb2158cf0fdcab3d89334641ccc670f7f93fda3
+  metadata.gz: 3ad70be9c0770932b1658509e19e58a9251c91fc7117f42a9191e4b4a9ec1e9bb4606ea33b7321561036df3969505b347f61ceb8b387ae8b75381f8db0bc0a41
+  data.tar.gz: a6cd09925a0d1bad7d62ec24f06970a4647f20de4d135e671bf2ed1681d0976d76670d1c87bf28d5d7121826a86b8b61891ddac87921f210c69cc3da9c2db559

data/.rubocop.yml

@@ -6,6 +6,9 @@ AllCops:
     - 'tmp/**/*'
     - '.git/**/*'
     - 'bin/*'
+Style/OpenStructUse:
+  Exclude:
+    - 'spec/integration/*'
 Style/ClassAndModuleChildren:
   Exclude: 
     - 'spec/**/*'

data/CHANGELOG.md

@@ -28,3 +28,10 @@
 
 ## [0.4.1] - 2023-12-29
 - Fix bug triggered when nesting each and if
+
+## [0.5.0] - 2024-01-01
+- Add support for `SetA = Interactify { _1.a = 'a' }`, lambda and block class creation syntax
+- Add support for organizing `organize A.organizing(B, C, D), E, F` contract syntax
+- make definition errors raise optionally
+- raise an error with unexpected keys in Interactify.if clause
+- propagate caller_info through chains

data/README.md

@@ -1,6 +1,6 @@
 # Interactify
 
-[![Gem Version](https://badge.fury.io/rb/interactify.svg)](https://badge.fury.io/rb/interactify)
+[![Gem Version](https://badge.fury.io/rb/interactify.svg?1704002847)](https://badge.fury.io/rb/interactify)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 ![Ruby 3.3.0](https://img.shields.io/badge/ruby-3.3.0-green.svg)
 ![Ruby 3.2.2](https://img.shields.io/badge/ruby-3.2.2-green.svg)
@@ -25,20 +25,30 @@ gem 'interactify'
 ```ruby
 # in config/initializers/interactify.rb
 Interactify.configure do |config|
-  # default
-  # config.root = Rails.root / 'app'
-end
+  # defaults
+  config.root = Rails.root / 'app'
 
-Interactify.on_contract_breach do |context, attrs|
-  # maybe add context to Sentry or Honeybadger etc here
-end
+  config.on_contract_breach do |context, contract_failures|
+    # maybe add context to Sentry or Honeybadger etc here
+  end
+
+  # called when an Interactify.organizing or Interactify.promising fails to match the actual interactor
+  # definitions
+  config.on_definition_error = Kernel.method(:raise)
 
-Interactify.before_raise do |exception|
-  # maybe add context to Sentry or Honeybadger etc here
+  # config.on_definition_error do |error|
+  #   # you may want to raise an error in test but not in production
+  #   # or you may want to log the error
+  # end
+
+  config.before_raise do |exception|
+    # maybe add context to Sentry or Honeybadger etc here
+  end
 end
 ```
 
 ### Using the RSpec matchers
+
 ```ruby
 # e.g. in spec/support/interactify.rb
 require 'interactify/rspec_matchers/matchers'
@@ -109,6 +119,24 @@ organize \
   Thing2
 ```
 
+Sometimes you also want a one liner but testability too.
+the `Interactify` method will take a block or a lambda and return an Interactify class.
+
+```ruby
+# passing a block
+DecorateOrder = Interactify do |context| 
+  context.order = context.order.decorate
+end
+
+# passing a lambda
+DecorateOrder = Interactify(some_lambda)
+
+# passing anything that responds to call
+# please note if you pass a class it will be instantiated first
+# so you can't pass a class with a constructor that takes arguments
+DecorateOrder = Interactify(callable_object)
+```
+
 ### Each/Iteration
 
 Sometimes we want an interactor for each item in a collection.
@@ -308,6 +336,54 @@ Actual promises are:
 step1
 ```
 
+### Organizing
+You can now annotate your interactors in the organize arguments with their sub-organizers' interactors. 
+This also serves as executable documentation, validated at load time, and is enforced to stay in sync.
+
+
+```ruby
+organize \
+  LoadOrder,
+  MarkAsPaid,
+  SendOutNotifications.organizing(
+    EmailUser,
+    SendPush,
+    NotifySomeThirdParty, 
+    SendOutNotifications::DoAnotherThing
+  )
+
+class SendOutNotifications
+  organize \
+    EmailUser,
+    SendPush,
+    NotifySomeThirdParty,
+    SetData = Interactify do |context|
+      context.data = {this: true}
+    end
+end
+```
+
+In this example, it might seem reasonable for an editor of SendOutNotifications to append SetData to the end of the chain. 
+However, the naming here is not ideal. 
+If it's generically named and not easily searchable, then the discoverability of the code is reduced.
+
+By invoking `.organizing` when the original author first uses `SendOutNotifications`, it encourages the subsequent editor to think about and document its own callers. 
+They may still choose to add `SetData` to the end of the chain, but this increases the chances of more easily finding where the data is changed.
+
+
+Example load time failure:
+```
+SendOutNotifications does not organize:
+[EmailUser, SendPush, NotifySomeThirdParty]
+
+Actual organized classes are:
+[EmailUser, SendPush, NotifySomeThirdParty, SendOutNotifications::SetData]
+
+Expected organized classes are:
+[SendOutNotifications::SetData]
+```
+
+
 ### Interactor wiring specs
 Sometimes you have an interactor chain that fails because something is expected deeper down the chain and not provided further up the chain. 
 The existing way to solve this is with enough integration specs to catch them, hunting and sticking a `byebug`, `debugger` or `binding.pry` in at suspected locations and inferring where in the chain the wiring went awry.

data/lib/interactify/configuration.rb

@@ -11,5 +11,13 @@ module Interactify
     def fallback
       Rails.root / "app" if Interactify.railties?
     end
+
+    def trigger_definition_error(error)
+      @on_definition_error&.call(error)
+    end
+
+    def on_definition_error(handler = nil, &block)
+      @on_definition_error = block_given? ? block : handler
+    end
   end
 end

data/lib/interactify/contracts/helpers.rb

@@ -4,6 +4,8 @@ require "interactify/async/jobable"
 require "interactify/contracts/call_wrapper"
 require "interactify/contracts/failure"
 require "interactify/contracts/setup"
+require "interactify/contracts/promising"
+require "interactify/contracts/organizing"
 require "interactify/dsl/organizer"
 
 module Interactify
@@ -11,6 +13,7 @@ module Interactify
     module Helpers
       extend ActiveSupport::Concern
 
+      # rubocop: disable Metrics/BlockLength
       class_methods do
         def expect(*attrs, filled: true)
           Setup.expects(context: self, attrs:, filled:)
@@ -24,6 +27,10 @@ module Interactify
           Promising.validate(self, *args)
         end
 
+        def organizing(*args)
+          Organizing.validate(self, *args)
+        end
+
         def promised_keys
           _interactify_extract_keys(contract.promises)
         end
@@ -50,6 +57,7 @@ module Interactify
           clauses.instance_eval { @terms }.json&.rules&.keys
         end
       end
+      # rubocop: enable Metrics/BlockLength
 
       included do
         c = Class.new(Contracts::Failure)

data/lib/interactify/contracts/mismatching_organizer_error.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "interactify/contracts/failure"
+
+module Interactify
+  module Contracts
+    class MismatchingOrganizerError < Contracts::Failure
+      def initialize(interactor, organizing, organized_klasses)
+        @interactor = interactor
+        @organizing = organizing
+        @organized_klasses = organized_klasses
+
+        super formatted_message
+      end
+
+      private
+
+      attr_reader :interactor, :organizing, :organized_klasses
+
+      def formatted_message
+        <<~MESSAGE.chomp.strip
+          #{interactor} does not organize:
+          #{organizing.inspect}
+
+          Actual organized classes are:
+          #{organized_klasses.inspect}
+
+          #{missing_and_extra_message}
+        MESSAGE
+      end
+
+      def extra = organizing - organized_klasses
+      def missing = organized_klasses - organizing
+      def missing_message = missing.none? ? nil : "Missing classes are:\n#{missing.inspect}"
+      def extra_message = extra.none? ? nil : "Extra classes are:\n#{extra.inspect}"
+
+      def missing_and_extra_message = [missing_message, extra_message].compact.join("\n\n")
+    end
+  end
+end

data/lib/interactify/contracts/organizing.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "interactify/contracts/mismatching_organizer_error"
+
+module Interactify
+  module Contracts
+    class Organizing
+      attr_reader :interactor, :organizing
+
+      def self.validate(interactor, *organizing)
+        new(interactor, *organizing).validate
+
+        interactor
+      end
+
+      def initialize(interactor, *organizing)
+        @interactor = interactor
+        @organizing = organizing
+      end
+
+      def validate
+        return if organizing == organized
+
+        Interactify.trigger_definition_error(
+          MismatchingOrganizerError.new(interactor, organizing, organized)
+        )
+      end
+
+      delegate :organized, to: :interactor
+    end
+  end
+end

data/lib/interactify/dsl/each_chain.rb

@@ -5,17 +5,23 @@ require "interactify/dsl/unique_klass_name"
 module Interactify
   module Dsl
     class EachChain
-      attr_reader :each_loop_klasses, :plural_resource_name, :evaluating_receiver
+      MissingIteratableValueInContext = Class.new(ArgumentError)
 
-      def self.attach_klass(evaluating_receiver, plural_resource_name, *each_loop_klasses)
-        iteratable = new(each_loop_klasses, plural_resource_name, evaluating_receiver)
+      attr_reader :each_loop_klasses, :plural_resource_name, :evaluating_receiver, :caller_info
+
+      def self.attach_klass(evaluating_receiver,
+                            *each_loop_klasses,
+                            plural_resource_name:,
+                            caller_info:)
+        iteratable = new(each_loop_klasses, plural_resource_name, evaluating_receiver, caller_info:)
         iteratable.attach_klass
       end
 
-      def initialize(each_loop_klasses, plural_resource_name, evaluating_receiver)
+      def initialize(each_loop_klasses, plural_resource_name, evaluating_receiver, caller_info:)
         @each_loop_klasses = each_loop_klasses
         @plural_resource_name = plural_resource_name
         @evaluating_receiver = evaluating_receiver
+        @caller_info = caller_info
       end
 
       # allows us to dynamically create an interactor chain
@@ -33,10 +39,17 @@ module Interactify
           end                                                                           #   end
 
           define_singleton_method(:source_location) do                                  #   def self.source_location
-            const_source_location this.evaluating_receiver.to_s                         #     [file, line]
+            file, line = this.caller_info&.split(':') 
+            return const_source_location(this.evaluating_receiver.to_s) if file.nil?
+
+            [file, line&.to_i]
           end                                                                           #   end
 
           define_method(:run!) do                                                       #  def run!
+            resources = context.send(this.plural_resource_name)                         #    packages = context.packages
+
+            bail_with_error(resources) unless resources.respond_to?(:each_with_index)   #    raise MissingIteratableValueInContext unless packages.respond_to?(:each_with_index)
+
             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
@@ -52,6 +65,11 @@ module Interactify
             context                                                                     #     context
           end                                                                           #   end
 
+          define_method(:bail_with_error) do |resources|
+            message = "Expected `context.#{this.plural_resource_name}`: #{resources.inspect}\nto respond to :each_with_index"
+            raise MissingIteratableValueInContext, message
+          end
+
           define_singleton_method(:klasses) do                                          #   def self.klasses
             klasses = instance_variable_get(:@klasses)                                  #     @klasses ||= Wrapper.wrap_many(self, [A, B, C])
             return klasses if klasses

data/lib/interactify/dsl/if_interactor.rb

@@ -6,18 +6,19 @@ require "interactify/dsl/if_klass"
 module Interactify
   module Dsl
     class IfInteractor
-      attr_reader :condition, :evaluating_receiver
+      attr_reader :condition, :evaluating_receiver, :caller_info
 
-      def self.attach_klass(evaluating_receiver, condition, succcess_interactor, failure_interactor)
-        ifable = new(evaluating_receiver, condition, succcess_interactor, failure_interactor)
+      def self.attach_klass(evaluating_receiver, condition, succcess_interactor, failure_interactor, caller_info:)
+        ifable = new(evaluating_receiver, condition, succcess_interactor, failure_interactor, caller_info:)
         ifable.attach_klass
       end
 
-      def initialize(evaluating_receiver, condition, succcess_arg, failure_arg)
+      def initialize(evaluating_receiver, condition, succcess_arg, failure_arg, caller_info:)
         @evaluating_receiver = evaluating_receiver
         @condition = condition
         @success_arg = succcess_arg
         @failure_arg = failure_arg
+        @caller_info = caller_info
       end
 
       def success_interactor
@@ -71,7 +72,7 @@ module Interactify
         case arg
         when Array
           name = "If#{condition.to_s.camelize}#{truthiness ? 'IsTruthy' : 'IsFalsey'}"
-          klass_basis.chain(name, *arg)
+          klass_basis.chain(name, *arg, caller_info:)
         else
           arg
         end

data/lib/interactify/dsl/if_klass.rb

@@ -19,7 +19,7 @@ module Interactify
       end
 
       def run!(context)
-        result = condition.is_a?(Proc) ? condition.call(context) : context.send(condition)
+        result = invoke_callable(context)
 
         interactor = result ? success_interactor : failure_interactor
         interactor.respond_to?(:call!) ? interactor.call!(context) : interactor&.call(context)
@@ -27,6 +27,42 @@ module Interactify
 
       private
 
+      def invoke_callable(context)
+        return handle_string_or_symbol(context) if string_or_symbol_condition?
+        return handle_interactor_subclass(context) if interactor_subclass_condition?
+        return handle_proc_or_class(context) if proc_or_class_condition?
+
+        raise_unknown_condition_error
+      end
+
+      def string_or_symbol_condition?
+        condition.class.in?([String, Symbol])
+      end
+
+      def handle_string_or_symbol(context)
+        context.send(condition)
+      end
+
+      def interactor_subclass_condition?
+        condition.is_a?(Class) && condition < Interactor
+      end
+
+      def handle_interactor_subclass(context)
+        condition.new(context).call
+      end
+
+      def proc_or_class_condition?
+        condition.is_a?(Proc) || condition.is_a?(Class)
+      end
+
+      def handle_proc_or_class(context)
+        condition.call(context)
+      end
+
+      def raise_unknown_condition_error
+        raise "Unknown condition: #{condition.inspect}"
+      end
+
       def attach_source_location
         attach do |_klass, this|
           define_singleton_method(:source_location) do            #   def self.source_location
@@ -38,7 +74,7 @@ module Interactify
       def attach_expectations
         attach do |klass, this|
           klass.expects do
-            required(this.condition) unless this.condition.is_a?(Proc)
+            required(this.condition.to_sym) if this.condition.class.in?([String, Symbol])
           end
         end
       end

data/lib/interactify/dsl/unique_klass_name.rb

@@ -5,7 +5,7 @@ module Interactify
     module UniqueKlassName
       def self.for(namespace, prefix)
         id = generate_unique_id
-        klass_name = :"#{prefix}#{id}"
+        klass_name = :"#{prefix.to_s.camelize.gsub("::", "__")}#{id}"
 
         while namespace.const_defined?(klass_name)
           id = generate_unique_id

data/lib/interactify/dsl/wrapper.rb

@@ -29,6 +29,12 @@ module Interactify
         when Array
           wrap_chain
         when Proc
+          wrap_proc
+        when Class
+          return interactor if interactor < Interactor
+
+          raise ArgumentError, "#{interactor} must respond_to .call" unless interactor.respond_to?(:call)
+
           wrap_proc
         else
           interactor

data/lib/interactify/dsl.rb

@@ -6,6 +6,9 @@ require "interactify/dsl/unique_klass_name"
 
 module Interactify
   module Dsl
+    Error = Class.new(::ArgumentError)
+    IfDefinitionUnexpectedKey = Class.new(Error)
+
     # creates a class in the attach_klass_to's namespace
     # e.g.
     #
@@ -15,25 +18,27 @@ module Interactify
     # 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)
+      caller_info = caller(1..1).first
+
       EachChain.attach_klass(
         self,
-        plural_resource_name,
-        *each_loop_klasses
+        *each_loop_klasses,
+        caller_info:,
+        plural_resource_name:
       )
     end
 
     def if(condition, success_arg, failure_arg = nil)
-      then_else = if success_arg.is_a?(Hash) && failure_arg.nil?
-                    success_arg.slice(:then, :else)
-                  else
-                    { then: success_arg, else: failure_arg }
-                  end
+      then_else = parse_if_args(condition, success_arg, failure_arg)
+
+      caller_info = caller(1..1).first
 
       IfInteractor.attach_klass(
         self,
         condition,
         then_else[:then],
-        then_else[:else]
+        then_else[:else],
+        caller_info:
       )
     end
 
@@ -54,7 +59,8 @@ module Interactify
     # 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: [])
+    def chain(klass_name, *chained_klasses, expect: [], caller_info: nil)
+      caller_info ||= caller(1..1).first
       expectations = expect
 
       klass = Class.new do                             # class EvaluatingNamespace::SomeClass
@@ -62,7 +68,7 @@ module Interactify
         expect(*expectations) if expectations.any?     #   expect :foo, :bar
 
         define_singleton_method(:source_location) do   #   def self.source_location
-          source_location                              #     [file, line]
+          caller_info                                  #     [file, line]
         end                                            #   end
 
         organize(*chained_klasses)                     #   organize(A, B, C)
@@ -73,5 +79,21 @@ module Interactify
       klass_name = UniqueKlassName.for(where_to_attach, klass_name)
       where_to_attach.const_set(klass_name, klass)
     end
+
+    private
+
+    def parse_if_args(condition, success_arg, failure_arg)
+      then_else = if success_arg.is_a?(Hash) && failure_arg.nil?
+                    extra_keys = success_arg.except(:then, :else)
+
+                    if extra_keys.any?
+                      raise IfDefinitionUnexpectedKey, "Unexpected keys: #{extra_keys.keys.join(", ")}"
+                    end
+
+                    success_arg.slice(:then, :else)
+                  else
+                    { then: success_arg, else: failure_arg }
+                  end
+      end
   end
 end

data/lib/interactify/interactify_callable.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "interactify/dsl/wrapper"
+
+# rubocop: disable Naming/MethodName
+def Interactify(method_callable = nil, &block)
+  to_wrap = method_callable || block
+
+  Interactify::Dsl::Wrapper.wrap(self, to_wrap)
+end
+# rubocop: enable Naming/MethodName

data/lib/interactify/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Interactify
-  VERSION = "0.4.1"
+  VERSION = "0.5.0"
 end

data/lib/interactify.rb

@@ -10,38 +10,43 @@ require "interactify/contracts/promising"
 require "interactify/dsl"
 require "interactify/wiring"
 require "interactify/configuration"
+require "interactify/interactify_callable"
 
 module Interactify
-  def self.railties_missing?
-    @railties_missing
-  end
+  class << self
+    delegate :on_definition_error, :trigger_definition_error, to: :configuration
 
-  def self.railties_missing!
-    @railties_missing = true
-  end
+    def railties_missing?
+      @railties_missing
+    end
 
-  def self.railties
-    railties?
-  end
+    def railties_missing!
+      @railties_missing = true
+    end
 
-  def self.railties?
-    !railties_missing?
-  end
+    def railties
+      railties?
+    end
 
-  def self.sidekiq_missing?
-    @sidekiq_missing
-  end
+    def railties?
+      !railties_missing?
+    end
 
-  def self.sidekiq_missing!
-    @sidekiq_missing = true
-  end
+    def sidekiq_missing?
+      @sidekiq_missing
+    end
 
-  def self.sidekiq
-    sidekiq?
-  end
+    def sidekiq_missing!
+      @sidekiq_missing = true
+    end
+
+    def sidekiq
+      sidekiq?
+    end
 
-  def self.sidekiq?
-    !sidekiq_missing?
+    def sidekiq?
+      !sidekiq_missing?
+    end
   end
 end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: interactify
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Mark Burns
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-12-31 00:00:00.000000000 Z
+date: 2024-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -96,7 +96,9 @@ files:
 - lib/interactify/contracts/call_wrapper.rb
 - lib/interactify/contracts/failure.rb
 - lib/interactify/contracts/helpers.rb
+- lib/interactify/contracts/mismatching_organizer_error.rb
 - lib/interactify/contracts/mismatching_promise_error.rb
+- lib/interactify/contracts/organizing.rb
 - lib/interactify/contracts/promising.rb
 - lib/interactify/contracts/setup.rb
 - lib/interactify/dsl.rb
@@ -106,6 +108,7 @@ files:
 - lib/interactify/dsl/organizer.rb
 - lib/interactify/dsl/unique_klass_name.rb
 - lib/interactify/dsl/wrapper.rb
+- lib/interactify/interactify_callable.rb
 - lib/interactify/rspec_matchers/matchers.rb
 - lib/interactify/version.rb
 - lib/interactify/wiring.rb