workflow_template 0.0.4

data/lib/workflow_template/definer/has_actions.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative '../performer'
+require_relative 'has_actions/actions'
+require_relative 'has_actions/nested'
+
+module WorkflowTemplate
+  module Definer
+    module HasActions
+      def actions
+        return @actions if frozen?
+
+        @own_actions ||= Actions::Unprepared.instance
+        return @own_actions.prepared unless defined?(superclass) && superclass.respond_to?(:actions)
+
+        superclass.actions.merge(@own_actions)
+      end
+
+      def freeze
+        unless frozen?
+          @actions = prepare_actions
+          @own_actions = nil
+        end
+
+        super
+      end
+
+      protected
+
+      def prepare_actions
+        actions
+      end
+
+      def store_action(action, position)
+        @own_actions ||= Actions::Unprepared.instance
+        @own_actions.add_simple(action, position)
+      end
+
+      def store_wrapper_action(action)
+        @own_actions ||= Actions::Unprepared.instance
+        @own_actions.add_wrapper(action)
+      end
+    end
+  end
+end

data/lib/workflow_template/definer/has_default_state_transition_strategy.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative '../state'
+require_relative '../workflow/description'
+
+module WorkflowTemplate
+  module Definer
+    module HasDefaultStateTransitionStrategy
+      Workflow::Description.register(:initialize, :state) do |workflow|
+        "state: #{workflow.default_state_transition_strategy}"
+      end
+
+      def default_state_transition_strategy(*args)
+        case args.length
+        when 0
+          return @default_state_transition_strategy if defined? @default_state_transition_strategy
+          if defined?(superclass) && superclass.respond_to?(:default_state_transition_strategy)
+            return superclass.default_state_transition_strategy
+          end
+
+          :merge
+        when 1 then @default_state_transition_strategy = State.normalize_transition_strategy(args[0])
+        else raise Error, "Unexpected arguments for state transition strategy: '#{args}'"
+        end
+      end
+
+      def freeze
+        @default_state_transition_strategy = default_state_transition_strategy unless frozen?
+
+        super
+      end
+    end
+  end
+end

data/lib/workflow_template/definer/has_output_normalizer.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative '../state'
+require_relative '../workflow/description'
+
+module WorkflowTemplate
+  module Definer
+    module HasOutputNormalizer
+      Workflow::Description.register(:finalize, :output_normalizer) do |workflow|
+        next if workflow.send(:output_normalizer).keys.nil?
+
+        "normalizes output: #{workflow.send(:output_normalizer).keys.join(', ')}"
+      end
+
+      def normalize_output(*keys)
+        @output_normalizer = State::Normalizer.instance(keys)
+      end
+
+      def freeze
+        @output_normalizer = output_normalizer unless frozen?
+
+        super
+      end
+
+      protected
+
+      def output_normalizer
+        return @output_normalizer if defined? @output_normalizer
+        return State::Normalizer.instance unless defined?(superclass) && superclass.respond_to?(:output_normalizer)
+
+        superclass.output_normalizer
+      end
+    end
+  end
+end

data/lib/workflow_template/definer/has_state_adapter.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative '../adapters/state/default'
+require_relative '../workflow/description'
+
+module WorkflowTemplate
+  module Definer
+    module HasStateAdapter
+      def state_adapter(*args)
+        case args.length
+        when 0
+          return @state_adapter if defined? @state_adapter
+          if defined?(superclass) && superclass.respond_to?(:state_adapter)
+            return superclass.state_adapter
+          end
+
+          State::Adapter.fetch(:default)
+        when 1 then @state_adapter = State::Adapter.fetch(args[0])
+        else raise Error, "Unexpected arguments for state adapter: '#{args}'"
+        end
+      end
+
+      def freeze
+        @state_adapter = state_adapter unless frozen?
+
+        super
+      end
+    end
+  end
+end

data/lib/workflow_template/definer/has_validations/action.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module WorkflowTemplate
+  module Definer
+    module HasValidations
+      class Action
+        def initialize(action, validations)
+          @action = action
+          @validations = validations
+        end
+
+        attr_reader :validations
+
+        private
+
+        attr_reader :action
+      end
+    end
+  end
+end

data/lib/workflow_template/definer/has_validations/description.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative '../../workflow/description'
+
+module WorkflowTemplate
+  module Definer
+    module HasValidations
+      module Description
+        Workflow::Description.register(:initialize, :input_validations) do |workflow|
+          next if void?(workflow.send(:validations).input)
+
+          "validates input: #{describe_entry(workflow.send(:validations).input)}"
+        end
+
+        Workflow::Description.register(:finalize, :output_validations) do |workflow|
+          next if void?(workflow.send(:validations).output)
+
+          "validates output: #{describe_entry(workflow.send(:validations).output)}"
+        end
+
+        def self.describe_entry(entry)
+          case entry
+          when Array then "{ #{entry.join(', ')} }"
+          else entry
+          end
+        end
+
+        def self.void?(entry)
+          case entry
+          when nil then true
+          when Symbol then false
+          else entry.empty?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/workflow_template/definer/has_validations/validations.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require 'set'
+require 'forwardable'
+require_relative '../../error'
+require_relative '../../validation/evaluation/abstract'
+
+module WorkflowTemplate
+  module Definer
+    module HasValidations
+      module Validations
+        def self.merge_entries(current_entry, new_entry)
+          new_entry = normalize_entry(new_entry)
+          return new_entry if current_entry.nil?
+          return current_entry if new_entry.nil?
+
+          entry_to_set(current_entry) | entry_to_set(new_entry)
+        end
+
+        def self.entry_to_set(entry)
+          case entry
+          when Set then entry
+          when Array then entry.to_set
+          else Set.new([entry])
+          end
+        end
+
+        def self.normalize_entry(entry)
+          case entry
+          when nil then nil
+          when Array, Set then entry.to_a.to_set(&:to_sym)
+          else entry.to_sym
+          end
+        end
+
+        class Unprepared
+          def self.instance
+            new
+          end
+
+          attr_reader :declarations
+
+          def initialize(declarations: {}, input_set: nil, output_set: nil)
+            @declarations = declarations.freeze
+            @input_set = Validations.normalize_entry(input_set)
+            @output_set = Validations.normalize_entry(output_set)
+          end
+
+          private_class_method :new
+
+          def add(declaration)
+            raise Error, "Declaration name taken: '#{declaration.name}'" if @declarations.key? declaration.name
+            raise Error, "Validation '#{declaration.name}' not properly declared" unless valid_declaration?(declaration)
+
+            @declarations = declarations.merge(declaration.name => declaration).freeze
+            declaration
+          end
+
+          def validate_input(entry)
+            @input_set = Validations.merge_entries(@input_set, entry)
+          end
+
+          def validate_output(entry)
+            @output_set = Validations.merge_entries(@output_set, entry)
+          end
+
+          def prepared
+            Prepared.instance declarations: declarations, input: input_set, output: output_set
+          end
+
+          def freeze
+            raise Error, "Freeze is unimplemented for #{self.class.name}, call #prepared instead"
+          end
+
+          protected
+
+          attr_reader :input_set, :output_set
+
+          def valid_declaration?(declaration)
+            declaration.is_a?(Validation::Evaluation::Abstract)
+          end
+        end
+
+        class Prepared
+          attr_reader :declarations, :input, :output
+
+          def self.instance(declarations:, input:, output:)
+            new(declarations, normalize_entry(input), normalize_entry(output))
+          end
+
+          def self.normalize_entry(entry)
+            case entry
+            when nil then nil
+            when Array, Set then entry.to_a.map(&:to_sym)
+            else entry.to_sym
+            end
+          end
+
+          private_class_method :new
+
+          def initialize(declarations, input, output)
+            @declarations = declarations.freeze
+            @input = input.freeze
+            @output = output.freeze
+            freeze
+          end
+
+          def merge(other)
+            merged_validations = declarations.merge other.declarations
+            merged_input = Validations.merge_entries(input, other.send(:input_set))
+            merged_output = Validations.merge_entries(output, other.send(:output_set))
+
+            Prepared.instance(
+              declarations: merged_validations,
+              input: merged_input,
+              output: merged_output
+            )
+          end
+
+          def resolve_validations(option)
+            case option
+            when nil then nil
+            when Array then option.map { |element| resolve_validation(element) }.freeze
+            else resolve_validation(option).freeze
+            end
+          end
+
+          def resolve_validation(name)
+            name = name.to_sym
+            raise Error, "Validation not declared: #{name}" unless declarations.key? name
+
+            declarations[name]
+          end
+
+          def resolved
+            Resolved.new(self)
+          end
+        end
+
+        class Resolved
+          extend Forwardable
+
+          def_delegators :@prepared, :declarations
+          def_delegators :@prepared, :input
+          def_delegators :@prepared, :output
+
+          def_delegators :@prepared, :merge
+          def_delegators :@prepared, :resolve_validations
+
+          def initialize(prepared)
+            @prepared = prepared
+            @input_validations = prepared.resolve_validations(prepared.input)
+            @output_validations = prepared.resolve_validations(prepared.output)
+            freeze
+          end
+
+          attr_reader :input_validations, :output_validations
+        end
+      end
+    end
+  end
+end

data/lib/workflow_template/definer/has_validations.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative '../validation/adapter'
+require_relative '../validation/builder/proxy'
+require_relative '../adapters/validation/generic'
+require_relative 'has_validations/validations'
+
+module WorkflowTemplate
+  module Definer
+    module HasValidations
+      def default_validation_adapter(*args)
+        case args.length
+        when 0
+          return @default_validation_adapter if defined? @default_validation_adapter
+          if defined?(superclass) && superclass.respond_to?(:default_validation_adapter)
+            return superclass.default_validation_adapter
+          end
+
+          :default
+        when 1 then @default_validation_adapter = args[0]
+        else raise Error, "Unexpected arguments for default validation adapter: '#{args}'"
+        end
+      end
+
+      def declare_validation(name = nil, using: default_validation_adapter)
+        adapter = Validation::Adapter.fetch(using)
+
+        Validation::Builder::Proxy
+          .instance(adapter, own_validations, name: name)
+      end
+
+      def validate_input(keys)
+        own_validations.validate_input(keys)
+      end
+
+      def validate_output(keys)
+        own_validations.validate_output(keys)
+      end
+
+      def freeze
+        unless frozen?
+          @default_validation_adapter = default_validation_adapter
+          @validations = validations.resolved
+          @own_validations = nil
+        end
+
+        super
+      end
+
+      protected
+
+      def prepare_action(action)
+        super.prepare(validations)
+      end
+
+      def validations
+        return @validations if defined? @validations
+        return own_validations.prepared unless defined?(superclass) && superclass.respond_to?(:validations, true)
+
+        superclass.validations.merge(own_validations)
+      end
+
+      private
+
+      def own_validations
+        @own_validations ||= Validations::Unprepared.instance
+      end
+    end
+  end
+end

data/lib/workflow_template/error.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module WorkflowTemplate
+  class Error < RuntimeError; end
+
+  class Fatal < Error
+    class ArgumentError < Fatal
+      def initialize(action_name, message)
+        full_message = "Argument mismatch in '#{action_name}': #{message}"
+
+        super(full_message)
+      end
+
+      def self.depth(argument_error, method)
+        path, = method.source_location
+        label = method.name.to_s
+        _, index = argument_error.backtrace_locations.each_with_index.find do |location, _index|
+          location.label == label && location.path == path
+        end
+
+        index
+      end
+    end
+
+    class InconsistentState < Fatal
+    end
+
+    class BadActionReturn < Fatal
+      def initialize(action_name, value)
+        full_message = <<~ERR.squish
+          Invalid return from '#{action_name}' action, nil or Hash expected,
+          got '#{value.inspect}' (#{value.class.name})
+        ERR
+
+        super(full_message)
+      end
+    end
+
+    class BadReturnKeys < Fatal
+      def initialize(action_name, keys)
+        keys = keys.map { |key| "'#{key.inspect}' (#{key.class.name})" }
+        full_message = "Invalid return from '#{action_name}' action, symbolic keys expected, got #{keys.join(', ')}"
+        super(full_message)
+      end
+    end
+
+    class BadValidationReturn < Fatal
+      def initialize(action_name)
+        full_message = "Invalid return from '#{action_name}' validation"
+        super(full_message)
+      end
+    end
+
+    class BadInput < Fatal
+      def initialize(value)
+        full_message = "Invalid input, Hash expected, got '#{value.inspect}' (#{value.class.name})"
+        super(full_message)
+      end
+    end
+
+    class Detailed < Fatal
+      def initialize(action_name, input, message)
+        full_message = "Fatal error in '#{action_name}': #{message}, input: #{input.inspect}"
+        super(full_message)
+      end
+    end
+
+    class ForeignCodeError < Fatal
+      attr_reader :foreign_error
+
+      def initialize(foreign_error)
+        @foreign_error = foreign_error
+        full_message = "Foreign error #{foreign_error.class.name}: #{foreign_error.message}"
+        super(full_message)
+      end
+    end
+
+    class UnexpectedNil < Fatal
+      def initialize(action_name)
+        full_message = "Nil return from '#{action_name}', nil is not allowed for 'update' state transition strategy"
+        super(full_message)
+      end
+    end
+
+    class Unimplemented < Fatal
+      def initialize(action_name)
+        super("Unimplemented method: '#{action_name}'")
+      end
+    end
+  end
+
+  class ExecutionError < Error
+    def initialize(original_error)
+      @original_error = original_error
+      super(original_error.to_s)
+      freeze
+    end
+  end
+end

data/lib/workflow_template/outcome/block.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative '../validation/result/failure'
+
+module WorkflowTemplate
+  class Outcome
+    class Block
+      attr_reader :handler
+
+      def initialize(handler, binding)
+        @handler = handler
+        @binding = binding
+      end
+
+      def ok(&block)
+        handle_status(:ok, &block)
+      end
+
+      def invalid(&block)
+        handle_status(:error, matcher: Validation::Result::Failure, &block)
+      end
+
+      def error(match = nil, &block)
+        handle_status(:error, matcher: match, &block)
+      end
+
+      def otherwise(&block)
+        self.handler = handler.otherwise(binding: binding, &block)
+      end
+
+      def otherwise_unwrap(slice: nil, fetch: nil)
+        self.handler = handler.otherwise_unwrap(slice: slice, fetch: fetch)
+      end
+
+      def otherwise_raise(error: nil)
+        handler = handler()
+        self.handler = handler.otherwise(binding: binding) do |_|
+          error ||= Error.new("Unhandled workflow status: '#{handler.final_state.status}'")
+          raise error
+        end
+      end
+
+      def delegate_to(proc)
+        instance_eval(&proc)
+      end
+
+      private
+
+      attr_reader :binding
+      attr_writer :handler
+
+      def handle_status(status, **opts, &block)
+        self.handler = handler.handle_status(status, binding: binding, **opts, &block)
+        self
+      end
+    end
+  end
+end

data/lib/workflow_template/outcome/handler.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+require_relative 'statuses'
+require_relative '../validation/error'
+
+module WorkflowTemplate
+  class Outcome
+    class Handler
+      extend Forwardable
+
+      attr_reader :final_state, :retval
+
+      def_delegator :@statuses, :unhandled?
+      def_delegator :@statuses, :default_missing?
+      def_delegator :@statuses, :default_missing
+
+      def initialize(final_state, statuses: Outcome::Statuses.new, retval: nil)
+        @final_state = final_state
+        @statuses = statuses
+        @retval = retval
+        freeze
+      end
+
+      def handle_status(status, binding: nil, **opts, &block) # rubocop:disable Metrics/AbcSize
+        status = status.to_sym
+        raise WorkflowTemplate::Error, "Handler for '#{status}' unexpected" if @statuses[status].default?
+
+        statuses = @statuses.on_default_detected(status, self.class.default?(status, **opts))
+        if unhandled?(final_state.status) && self.class.run_handler?(status, final_state, **opts)
+          self.class.run_handler(status, statuses, final_state, binding: binding, &block)
+        else
+          Handler.new(final_state, statuses: statuses, retval: retval)
+        end
+      end
+
+      def otherwise(binding: nil, &block)
+        statuses = @statuses.all_defaults!
+        if unhandled?(final_state.status)
+          self.class.run_handler(final_state.status, statuses, final_state, binding: binding, &block)
+        else
+          Handler.new(final_state, statuses: statuses, retval: retval)
+        end
+      end
+
+      def otherwise_unwrap(slice: nil, fetch: nil)
+        statuses = @statuses.all_defaults!
+        if unhandled?(final_state.status)
+          Handler.new(
+            final_state,
+            statuses: statuses.handled!(final_state.status),
+            retval: final_state.unwrap(slice: slice, fetch: fetch)
+          )
+        else
+          Handler.new(final_state, statuses: statuses, retval: retval)
+        end
+      end
+
+      def self.run_handler(status, statuses, final_state, binding: nil, &block)
+        statuses = statuses.handled!(status)
+        retval = final_state.state_class.run_handler!(final_state, binding, &block)
+        Handler.new(final_state, statuses: statuses, retval: retval)
+      end
+
+      def self.default?(status, **opts)
+        handler_strategy(status).default?(**opts)
+      end
+
+      def self.run_handler?(status, final_state, **opts)
+        return false unless status == final_state.status
+
+        handler_strategy(status).run_handler?(final_state, **opts)
+      end
+
+      def self.handler_strategy(status)
+        case status
+        when :ok then Ok
+        when :error then Error
+        else raise WorkflowTemplate::Error, "Unexpected status '#{status}'"
+        end
+      end
+
+      module Ok
+        def self.default?
+          true
+        end
+
+        def self.run_handler?(_final_state)
+          true
+        end
+      end
+
+      module Error
+        def self.default?(matcher: nil)
+          matcher.nil?
+        end
+
+        def self.run_handler?(final_state, matcher: nil)
+          # rubocop:disable Style/CaseEquality
+          matcher.nil? || matcher === final_state.error
+          # rubocop:enable Style/CaseEquality
+        end
+      end
+    end
+  end
+end