u-case 5.5.0 → 5.7.0

data/lib/micro/case/check.rb

@@ -60,6 +60,67 @@ module Micro
           Kind::Hash[arg]
         end
 
+        def flow_steps_kwarg!(args, steps, label)
+          return unless args && steps
+
+          raise ArgumentError,
+            "#{label} accepts a positional collection OR `steps:`, not both"
+        end
+
+        def transaction_kwarg!(value)
+          return nil if value.nil? || value == false
+          return true if value == true
+
+          if value.is_a?(Class)
+            transaction_owner!(value)
+            return value
+          end
+
+          if value.is_a?(Hash)
+            extra = value.keys - [:with]
+
+            raise ArgumentError,
+              "transaction: unsupported key(s) #{extra.inspect} (only `:with` is accepted)" unless extra.empty?
+
+            with = value[:with]
+            transaction_owner!(with)
+
+            return with
+          end
+
+          raise ArgumentError,
+            "transaction: #{value.inspect} is not supported (accepts `true`, `false`, `nil`, or `{ with: SomeARClass }`)"
+        end
+
+        def activerecord_loaded!
+          return if defined?(::ActiveRecord::Base)
+
+          raise ::Micro::Cases::Error::TransactionAdapterMissing
+        end
+
+        # Validates a transaction owner class. We accept Class instances
+        # only; the AR-subclass check is enforced if (and only if)
+        # ActiveRecord is already loaded — otherwise we defer to runtime
+        # so that load-order quirks (Rails initializers running before
+        # the AR autoload) don't break class-eval-time declarations.
+        def transaction_owner!(klass)
+          raise ArgumentError,
+            "transaction owner #{klass.inspect} must be a subclass of ActiveRecord::Base" unless klass.is_a?(Class)
+
+          return unless defined?(::ActiveRecord::Base)
+          return if klass <= ::ActiveRecord::Base
+
+          raise ArgumentError,
+            "transaction owner #{klass.inspect} must be a subclass of ActiveRecord::Base"
+        end
+
+        def transaction_class_callback!(callable)
+          return if callable.respond_to?(:call)
+
+          raise ArgumentError,
+            "Micro::Case.config.default_transaction_class= expects a callable (a block, lambda or proc), got #{callable.inspect}"
+        end
+
         def results_contract!(use_case_class, kind, type, value)
           contract = use_case_class.__results_contract__
           return unless contract
@@ -108,6 +169,16 @@ module Micro
         def flow_use_cases!(_use_cases); end
         def map_args!(_args); end
         def hash!(arg); arg; end
+        def flow_steps_kwarg!(_args, _steps, _label); end
+        def transaction_kwarg!(value)
+          return true if value == true
+          return value if value.is_a?(Class)
+          return value[:with] if value.is_a?(Hash) && value[:with].is_a?(Class)
+          nil
+        end
+        def activerecord_loaded!; end
+        def transaction_owner!(_klass); end
+        def transaction_class_callback!(_callable); end
         def results_contract!(_use_case_class, _kind, _type, _value); end
       end
     end

data/lib/micro/case/config.rb

@@ -52,6 +52,22 @@ module Micro
 
         @activemodel_validation_errors_failure = :invalid_attributes
       end
+
+      DEFAULT_TRANSACTION_CLASS_CALLBACK = -> { ::ActiveRecord::Base }.freeze
+
+      def default_transaction_class=(callable)
+        ::Micro::Case.check.transaction_class_callback!(callable)
+
+        @default_transaction_class = callable
+      end
+
+      def default_transaction_class(&block)
+        return self.default_transaction_class = block if block
+
+        return @default_transaction_class if defined?(@default_transaction_class)
+
+        DEFAULT_TRANSACTION_CLASS_CALLBACK
+      end
     end
   end
 end

data/lib/micro/case/result.rb

@@ -50,6 +50,32 @@ module Micro
         @__success ? :success : :failure
       end
 
+      def deconstruct
+        [@__success ? :success : :failure, type, data]
+      end
+
+      def deconstruct_keys(keys)
+        if keys.nil?
+          hash = { type: type, data: data, result: data, use_case: use_case, transitions: transitions }
+          hash[@__success ? :success : :failure] = type
+          return hash
+        end
+
+        hash = {}
+        keys.each do |key|
+          case key
+          when :type        then hash[:type]        = type
+          when :data        then hash[:data]        = data
+          when :result      then hash[:result]      = data
+          when :use_case    then hash[:use_case]    = use_case
+          when :transitions then hash[:transitions] = transitions
+          when :success     then hash[:success]     = type if @__success
+          when :failure     then hash[:failure]     = type if !@__success
+          end
+        end
+        hash
+      end
+
       def [](key)
         data[key]
       end

data/lib/micro/case/version.rb

@@ -2,6 +2,6 @@
 
 module Micro
   class Case
-    VERSION = '5.5.0'.freeze
+    VERSION = '5.7.0'.freeze
   end
 end

data/lib/micro/case.rb

@@ -63,8 +63,11 @@ module Micro
       Proc.new { |arg| call(arg) }
     end
 
-    def self.flow(*args)
-      @__flow_use_cases = Cases::Utils.map_use_cases(args)
+    def self.flow(*args, transaction: nil, steps: nil)
+      ::Micro::Case.check.flow_steps_kwarg!(args.empty? ? nil : args, steps, "#{self.name}.flow")
+
+      @__flow_use_cases = Cases::Utils.map_use_cases(steps || args)
+      @__flow_transaction = transaction
     end
 
     def self.results(&block)
@@ -81,6 +84,19 @@ module Micro
       parent.respond_to?(:__results_contract__) ? parent.__results_contract__ : nil
     end
 
+    def self.transaction(with:)
+      ::Micro::Case.check.transaction_owner!(with)
+
+      @__transaction_class = with
+    end
+
+    def self.__transaction_class__
+      return @__transaction_class if defined?(@__transaction_class)
+
+      parent = superclass
+      parent.respond_to?(:__transaction_class__) ? parent.__transaction_class__ : nil
+    end
+
     class << self
       alias __call__ call
 
@@ -129,7 +145,17 @@ module Micro
 
       self.class_eval('def use_cases; self.class.use_cases; end')
 
-      @__flow = __flow_builder__.build(args)
+      @__flow = __flow_builder__.build(args, transaction: __resolved_flow_transaction)
+    end
+
+    private_class_method def self.__flow_transaction
+      return @__flow_transaction if defined?(@__flow_transaction)
+    end
+
+    private_class_method def self.__resolved_flow_transaction
+      return __transaction_class__ || true if __flow_transaction == true
+
+      __flow_transaction
     end
 
     FLOW_STEP = 'Self'.freeze
@@ -301,15 +327,31 @@ module Micro
         @__result.__set__(is_success, value, type, self)
       end
 
-      def transaction(adapter = :activerecord)
-        raise NotImplementedError unless adapter == :activerecord
+      def transaction(adapter = nil, with: nil)
+        # Backward-compat shim for the pre-5.6.0 positional form:
+        #   transaction(:activerecord) { ... }
+        # The `:activerecord` value was the only positional value the
+        # helper ever accepted on prior versions. Anything else raises.
+        if adapter
+          raise ArgumentError,
+            "transaction(#{adapter.inspect}) is not supported; use transaction(with: SomeARClass) or transaction without arguments" unless adapter == :activerecord
+        end
+
+        ::Micro::Case.check.transaction_owner!(with) if with
+
+        owner = with || self.class.__transaction_class__
+
+        if owner.nil?
+          ::Micro::Case.check.activerecord_loaded!
+          owner = Config.instance.default_transaction_class.call
+        end
 
         result = nil
 
-        ActiveRecord::Base.transaction do
+        owner.transaction do
           result = yield
 
-          raise ActiveRecord::Rollback if result.failure?
+          raise ::ActiveRecord::Rollback if result.failure?
         end
 
         result

data/lib/micro/cases/error.rb

@@ -7,6 +7,15 @@ module Micro
       class InvalidUseCases < ArgumentError
         def initialize; super('argument must be a collection of `Micro::Case` classes'.freeze); end
       end
+
+      class TransactionAdapterMissing < RuntimeError
+        def initialize
+          super(
+            'transaction: true requires ActiveRecord to be loaded. '\
+            "Add `require 'active_record'` (or `gem 'activerecord'` to your Gemfile) before invoking the flow.".freeze
+          )
+        end
+      end
     end
 
   end

data/lib/micro/cases/flow.rb

@@ -8,30 +8,31 @@ module Micro
 
       attr_reader :use_cases
 
-      def self.build(args)
+      def self.build(args, transaction: nil)
         use_cases = Utils.map_use_cases(args)
 
         ::Micro::Case.check.flow_use_cases!(use_cases)
 
-        new(use_cases)
+        new(use_cases, transaction: transaction)
       end
 
-      def initialize(use_cases)
+      def initialize(use_cases, transaction: nil)
         @use_cases = use_cases.dup.freeze
         @next_ones = use_cases.dup
         @first = @next_ones.shift
+        @transaction = ::Micro::Case.check.transaction_kwarg!(transaction)
       end
 
       def inspect
-        '#<(%s) use_cases=%s>' % [self.class, @use_cases]
+        return '#<(%s) use_cases=%s>' % [self.class, @use_cases] unless @transaction
+
+        '#<(%s) transaction=%p use_cases=%s>' % [self.class, @transaction, @use_cases]
       end
 
       def call!(input:, result:)
-        first_result = __call_use_case(@first, result, input)
-
-        return first_result if @next_ones.empty?
+        return __call_steps(input, result) unless @transaction
 
-        __call_next_use_cases(first_result)
+        __wrap_in_transaction { __call_steps(input, result) }
       end
 
       def call(input = Kind::Empty::HASH)
@@ -75,6 +76,43 @@ module Micro
           raise Case::Error::InvalidInvocationOfTheThenMethod.new("#{self.class.name}#")
         end
 
+        def __call_steps(input, result)
+          first_result = __call_use_case(@first, result, input)
+
+          return first_result if @next_ones.empty?
+
+          __call_next_use_cases(first_result)
+        end
+
+        def __wrap_in_transaction
+          owner = __transaction_owner
+
+          result = nil
+
+          owner.transaction do
+            result = yield
+
+            raise ::ActiveRecord::Rollback if result.failure?
+          end
+
+          result
+        end
+
+        def __transaction_owner
+          return @transaction if @transaction.is_a?(Class)
+
+          callback = ::Micro::Case::Config.instance.default_transaction_class
+
+          # Only the gem's default callback (`-> { ActiveRecord::Base }`)
+          # needs the AR-loaded guard. A user-supplied callback can
+          # return whatever class they want — we trust it.
+          if callback.equal?(::Micro::Case::Config::DEFAULT_TRANSACTION_CLASS_CALLBACK)
+            ::Micro::Case.check.activerecord_loaded!
+          end
+
+          callback.call
+        end
+
         def __call_use_case(use_case, result, input)
           __build_use_case(use_case, result, input).__call__
         end

data/lib/micro/cases.rb

@@ -8,16 +8,24 @@ require 'micro/cases/map'
 
 module Micro
   module Cases
-    def self.flow(args)
-      Flow.build(args)
+    def self.flow(args = nil, transaction: nil, steps: nil)
+      args = nil if args.is_a?(Array) && args.empty?
+
+      ::Micro::Case.check.flow_steps_kwarg!(args, steps, 'Micro::Cases.flow')
+
+      Flow.build(steps || args, transaction: transaction)
     end
 
-    def self.safe_flow(args)
+    def self.safe_flow(args = nil, transaction: nil, steps: nil)
       if Case::Config.instance.disable_safe_features
         raise Case::Error::SafeFeaturesDisabled.new('Micro::Cases.safe_flow')
       end
 
-      Safe::Flow.build(args)
+      args = nil if args.is_a?(Array) && args.empty?
+
+      ::Micro::Case.check.flow_steps_kwarg!(args, steps, 'Micro::Cases.safe_flow')
+
+      Safe::Flow.build(steps || args, transaction: transaction)
     end
 
     def self.map(args)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: u-case
 version: !ruby/object:Gem::Version
-  version: 5.5.0
+  version: 5.7.0
 platform: ruby
 authors:
 - Rodrigo Serradura