u-case 5.4.0 → 5.6.0

data/lib/micro/case/check.rb

@@ -59,6 +59,99 @@ module Micro
         def hash!(arg)
           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
+          return unless type.is_a?(Symbol)
+          return if value.is_a?(Exception)
+
+          if kind == :success
+            declared = contract.success_declared?(type)
+            declared_types = contract.successes.keys
+            required = contract.success_keys(type) if declared
+          else
+            declared = contract.failure_declared?(type)
+            declared_types = contract.failures.keys
+            required = contract.failure_keys(type) if declared
+          end
+
+          raise Error::UnexpectedResultType.new(use_case_class, kind, type, declared_types) unless declared
+          return if required.nil? || required.empty?
+
+          if value.is_a?(Hash)
+            data_keys = value.keys.map { |k| k.is_a?(String) ? k.to_sym : k }
+          elsif value.is_a?(Symbol)
+            data_keys = [type]
+          else
+            return
+          end
+
+          missing = required - data_keys
+
+          raise Error::MissingResultKeys.new(use_case_class, kind, type, missing) unless missing.empty?
+        end
       end
 
       module Disabled
@@ -76,6 +169,17 @@ 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
   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/error.rb

@@ -60,9 +60,32 @@ module Micro
         end
       end
 
+      class UnexpectedResultType < TypeError
+        def initialize(use_case_class, kind, type, declared_types)
+          declared_list = declared_types.map { |t| ":#{t}" }.join(', ')
+          declared_list = '(none)' if declared_list.empty?
+
+          super(
+            "#{use_case_class.name} declared a results contract — " \
+            "#{kind} type :#{type} is not declared. Declared #{kind} types: #{declared_list}."
+          )
+        end
+      end
+
+      class MissingResultKeys < ArgumentError
+        def initialize(use_case_class, kind, type, missing_keys)
+          missing_list = missing_keys.map { |k| ":#{k}" }.join(', ')
+
+          super(
+            "#{use_case_class.name} declared a results contract — " \
+            "#{kind} :#{type} is missing required result keys: #{missing_list}."
+          )
+        end
+      end
+
       def self.by_wrong_usage?(exception)
         case exception
-        when Kind::Error, ArgumentError, InvalidResult, UnexpectedResult then true
+        when Kind::Error, ArgumentError, InvalidResult, UnexpectedResult, UnexpectedResultType then true
         else false
         end
       end

data/lib/micro/case/result/contract.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Micro
+  class Case
+    class Result
+      class Contract
+        attr_reader :successes, :failures
+
+        def self.define(&block)
+          contract = new
+          block.call(Definition.new(contract))
+          contract
+        end
+
+        def initialize
+          @successes = {}
+          @failures = {}
+        end
+
+        def add_success(type, keys)
+          @successes[type] = Array(keys).map(&:to_sym)
+        end
+
+        def add_failure(type, keys)
+          @failures[type] = Array(keys).map(&:to_sym)
+        end
+
+        def success_declared?(type)
+          @successes.key?(type)
+        end
+
+        def failure_declared?(type)
+          @failures.key?(type)
+        end
+
+        def success_keys(type)
+          @successes[type]
+        end
+
+        def failure_keys(type)
+          @failures[type]
+        end
+
+        class Definition
+          def initialize(contract)
+            @contract = contract
+          end
+
+          def success(type = :ok, result: nil)
+            @contract.add_success(Kind::Symbol[type], result)
+          end
+
+          def failure(type = :error, result: nil)
+            @contract.add_failure(Kind::Symbol[type], result)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/micro/case/version.rb

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

data/lib/micro/case.rb

@@ -11,6 +11,7 @@ module Micro
     require 'micro/case/utils'
     require 'micro/case/error'
     require 'micro/case/result'
+    require 'micro/case/result/contract'
     require 'micro/case/check'
     require 'micro/case/config'
     require 'micro/case/safe'
@@ -62,8 +63,38 @@ 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)
+      raise ArgumentError, 'a block is required'.freeze unless block
+      raise ArgumentError, 'must be called on a Micro::Case subclass, not on Micro::Case itself'.freeze if self == ::Micro::Case
+
+      @__results_contract = Result::Contract.define(&block)
+    end
+
+    def self.__results_contract__
+      return @__results_contract if defined?(@__results_contract)
+
+      parent = superclass
+      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
@@ -114,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
@@ -227,9 +268,10 @@ module Micro
       end
 
       def __failure_from_attributes_errors
-        Failure(
-          Config.instance.activemodel_validation_errors_failure,
-          result: { errors: attributes_errors }
+        __get_result(
+          false,
+          { errors: attributes_errors },
+          Config.instance.activemodel_validation_errors_failure
         )
       end
 
@@ -244,6 +286,8 @@ module Micro
       def Success(type = :ok, result: nil)
         value = result || type
 
+        ::Micro::Case.check.results_contract!(self.class, :success, type, value)
+
         __get_result(true, value, type)
       end
 
@@ -260,10 +304,11 @@ module Micro
 
         type = MapFailureType.call(value, type)
 
+        ::Micro::Case.check.results_contract!(self.class, :failure, type, value)
+
         __get_result(false, value, type)
       end
 
-
       def Check(type = nil, result: nil, on: Kind::Empty::HASH)
         result_key = type || :check
 
@@ -282,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.4.0
+  version: 5.6.0
 platform: ruby
 authors:
 - Rodrigo Serradura
@@ -122,6 +122,7 @@ files:
 - lib/micro/case/config.rb
 - lib/micro/case/error.rb
 - lib/micro/case/result.rb
+- lib/micro/case/result/contract.rb
 - lib/micro/case/result/transitions.rb
 - lib/micro/case/result/wrapper.rb
 - lib/micro/case/safe.rb