workflow_template 0.0.4

data/lib/workflow_template/outcome/status.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module WorkflowTemplate
+  class Outcome
+    class Status
+      def initialize(handled: false, default: false)
+        @handled = handled
+        @default = default
+        freeze
+      end
+
+      def handled?
+        @handled
+      end
+
+      def handled!
+        self.class.new(handled: true, default: default?)
+      end
+
+      def default?
+        @default
+      end
+
+      def default!
+        self.class.new(handled: handled?, default: true)
+      end
+
+      def inspect
+        "handled=#{handled?} default=#{default?}"
+      end
+    end
+  end
+end

data/lib/workflow_template/outcome/statuses.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative 'status'
+require_relative '../error'
+
+module WorkflowTemplate
+  class Outcome
+    class Statuses
+      def initialize(ok: Status.new, error: Status.new)
+        @statuses = { ok: ok, error: error }.freeze
+        freeze
+      end
+
+      def status(status)
+        status = status.to_sym
+        raise Error, "Unsupported status: '#{status}'" unless @statuses.key? status
+
+        @statuses[status]
+      end
+
+      def unhandled?(status)
+        !status(status).handled?
+      end
+
+      def default_missing?
+        @statuses.none? { |_, status| status.default? }
+      end
+
+      def default_missing
+        @statuses.reject { |_, status| status.default? }.keys
+      end
+
+      alias [] status
+
+      def handled!(status)
+        updated = status(status).handled!
+        self.class.new(**@statuses, status => updated)
+      end
+
+      def on_default_detected(status, detected)
+        return self unless detected
+
+        default!(status)
+      end
+
+      def default!(status)
+        updated = status(status).default!
+        self.class.new(**@statuses, status => updated)
+      end
+
+      def all_defaults!
+        self.class.new(**@statuses.transform_values(&:default!))
+      end
+
+      def inspect
+        "#<#{self.class.name} #{@statuses.map { |name, status| "#{name}: #{status.inspect}" }}>"
+      end
+    end
+  end
+end

data/lib/workflow_template/outcome.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+require_relative 'outcome/handler'
+require_relative 'outcome/block'
+
+module WorkflowTemplate
+  class Outcome
+    extend Forwardable
+
+    def initialize(state)
+      @handler = Handler.new(state)
+    end
+
+    def_delegator :handler, :retval
+    def_delegator :handler, :final_state
+
+    def_delegator :final_state, :meta
+    def_delegator :final_state, :status
+    def_delegator :final_state, :unwrap
+    def_delegator :final_state, :fetch
+    def_delegator :final_state, :slice
+    def_delegator :final_state, :to_result
+
+    def handle(&block)
+      binding = block.binding unless block.source_location.nil?
+      handler_block = Outcome::Block.new(handler, binding)
+
+      handler_block.instance_eval(&block)
+
+      self.handler = handler_block.handler
+      ensure_default_handled!
+
+      freeze
+
+      handler.retval
+    end
+
+    def data
+      final_state.bare_state
+    end
+
+    private
+
+    def ensure_default_handled!
+      return unless handler.default_missing?
+
+      raise Error, "Default handler missing for statuses: '#{handler.default_missing.join(', ')}'"
+    end
+
+    attr_accessor :handler
+  end
+end

data/lib/workflow_template/performer.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative 'error'
+
+module WorkflowTemplate
+  module Performer
+    def perform(state, receiver)
+      raise WorkflowTemplate::Fatal, 'Workflow is not frozen' unless frozen?
+
+      Performer.perform_wrapper_actions(state, actions, receiver)
+    end
+
+    def self.perform_wrapper_actions(state, actions, receiver)
+      if actions.wrapper.empty?
+        perform_actions(state, actions, receiver)
+      else
+        action, container = actions.next_wrapper_action
+        perform_wrapper_action(action, container, state, receiver)
+      end
+    end
+
+    def self.perform_wrapper_action(action, container, state, receiver)
+      inner_state = state
+      result = action.perform(state, receiver) do |yielded = {}|
+        inner_state = state.process_bare_result(yielded, action, trace: true, validate: false)
+        inner_state = perform_wrapper_actions(inner_state, container, receiver)
+        inner_state.wrapped_state
+      end
+      inner_state.process_wrapped_result(result, action, trace: false, validate: true)
+    end
+
+    def self.perform_actions(state, actions, receiver)
+      actions.simple.reduce(state) do |intermediate, action|
+        intermediate = perform_action(action, intermediate, receiver)
+
+        break intermediate unless intermediate.continue?
+
+        intermediate
+      end
+    end
+
+    def self.perform_action(action, state, *args)
+      action.perform(state, *args)
+    end
+  end
+end

data/lib/workflow_template/state/abstract.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'meta'
+
+module WorkflowTemplate
+  module State
+    module Abstract
+      attr_reader :wrapped_state, :meta
+
+      def initialize(wrapped_state, meta)
+        @wrapped_state = wrapped_state.freeze
+        @meta = meta.freeze
+        freeze
+      end
+
+      def bare_state
+        state_class.unwrap_success(wrapped_state)
+      end
+
+      def error?
+        state_class.error?(wrapped_state)
+      end
+
+      def error
+        state_class.unwrap_error(wrapped_state)
+      end
+
+      def state_class
+        raise NotImplementedError, "#{self.class.name}##{__method__} unimplemented"
+      end
+    end
+  end
+end

data/lib/workflow_template/state/adapter.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative '../error'
+
+module WorkflowTemplate
+  module State
+    module Adapter
+      def self.adapters
+        @adapters ||= {}
+      end
+
+      def self.register(name, adapter)
+        adapters[name.to_sym] = adapter
+      end
+
+      def self.fetch(name)
+        name = name.to_sym
+        raise Error, "Not a registered state adapter: #{name}" unless adapters.key? name
+
+        adapters[name]
+      end
+
+      module Abstract
+        module InstanceMethods
+        end
+
+        module ClassMethods
+          def canonical?(_wrapped_state)
+            raise NotImplementedError, "#{self.class.name}##{__method__} unimplemented"
+          end
+
+          def error?(_wrapped_state)
+            raise NotImplementedError, "#{self.class.name}##{__method__} unimplemented"
+          end
+
+          def wrap_success(_bare_state)
+            raise NotImplementedError, "#{self.class.name}##{__method__} unimplemented"
+          end
+
+          def unwrap_success(_wrapped_state)
+            raise NotImplementedError, "#{self.class.name}##{__method__} unimplemented"
+          end
+
+          def wrap_error_with_bare_state(_error, _bare_state)
+            raise NotImplementedError, "#{self.class.name}##{__method__} unimplemented"
+          end
+
+          def unwrap_error(_wrapped_state)
+            raise NotImplementedError, "#{self.class.name}##{__method__} unimplemented"
+          end
+
+          def map_unwrappable_state(_wrapped_state)
+            raise NotImplementedError, "#{self.class.name}##{__method__} unimplemented"
+          end
+
+          def flat_map_unwrappable_state(_wrapped_state)
+            raise NotImplementedError, "#{self.class.name}##{__method__} unimplemented"
+          end
+
+          def run_handler!(state, binding, &block)
+            raise NotImplementedError, "#{self.class.name}##{__method__} unimplemented"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/workflow_template/state/class_methods.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative 'validation'
+
+module WorkflowTemplate
+  module State
+    module ClassMethods
+      def initial(input, default_strategy, validations, trace: false)
+        wrapped_state = wrap_success(input)
+        wrapped_state = validate(wrapped_state, validations)
+        new wrapped_state, State.normalize_transition_strategy(default_strategy), Meta.instance(trace)
+      end
+
+      def validate(wrapped_state, validations)
+        raise Fatal::BadInput, wrapped_state unless canonical? wrapped_state
+
+        return wrapped_state if !Validation.applicable?(validations) || error?(wrapped_state)
+
+        flat_map_unwrappable_state(wrapped_state) do |bare_state|
+          result = Validation.validate(bare_state, validations)
+          result.success? ? wrapped_state : wrap_error_with_bare_state(result, bare_state)
+        end
+      end
+
+      def merge_bare_result(bare_state, bare_result, strategy, action_name)
+        ensure_canonical_bare_result!(bare_result, action_name)
+
+        if strategy == :merge
+          bare_state.merge(bare_result)
+        else
+          bare_result
+        end
+      end
+
+      def ensure_canonical_bare_result!(bare_result, action_name)
+        raise Fatal::BadActionReturn.new(action_name, bare_result) unless bare_result.is_a?(Hash)
+
+        faulty_keys = bare_result.keys.reject { _1.is_a?(Symbol) }
+        raise Fatal::BadReturnKeys.new(action_name, faulty_keys) unless faulty_keys.empty?
+      end
+    end
+  end
+end

data/lib/workflow_template/state/final.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative 'abstract'
+require_relative 'normalizer'
+require_relative '../validation/result/failure'
+require_relative '../validation/error'
+require_relative '../error'
+
+module WorkflowTemplate
+  module State
+    class Final
+      include Abstract
+
+      attr_reader :wrapped_state, :meta, :state_class
+
+      def initialize(wrapped_state, meta, state_class)
+        @state_class = state_class
+        super(wrapped_state, meta)
+      end
+
+      def status
+        error? ? :error : :ok
+      end
+
+      def unwrap(slice: nil, fetch: nil)
+        raise_error! if error?
+        return bare_state if slice.nil? && fetch.nil?
+
+        normalized_bare_state = Normalizer.instance(slice).normalize(bare_state)
+        fetch.nil? ? normalized_bare_state.values : normalized_bare_state.fetch(fetch, nil)
+      end
+
+      def fetch(key)
+        unwrap(fetch: key)
+      end
+
+      def slice(*keys)
+        unwrap(slice: keys)
+      end
+
+      def to_result(adapter = nil, **opts)
+        error? ? rewrap_error(adapter) : rewrap_success(adapter, **opts)
+      end
+
+      def raise_error!
+        error = state_class.unwrap_error(wrapped_state)
+
+        case error
+        when Exception then raise error
+        when WorkflowTemplate::Validation::Result::Failure then raise WorkflowTemplate::Validation::Error, error
+        else raise ExecutionError, error
+        end
+      end
+
+      private
+
+      def rewrap_error(adapter)
+        return wrapped_state if adapter.nil? || target_class(adapter).canonical?(wrapped_state)
+
+        target_class(adapter).wrap_error_with_bare_state(state_class.unwrap_error(wrapped_state), {})
+      end
+
+      def rewrap_success(adapter, **opts)
+        target_class(adapter).wrap_success(unwrap(**opts))
+      end
+
+      def target_class(adapter)
+        return state_class if adapter.nil?
+
+        State.state_class(State::Adapter.fetch(adapter))
+      end
+    end
+  end
+end

data/lib/workflow_template/state/intermediate.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative 'class_methods'
+require_relative 'final'
+
+module WorkflowTemplate
+  module State
+    module Intermediate
+      include Abstract
+
+      def initialize(wrapped_state, default_strategy, meta)
+        @default_strategy = default_strategy
+        super(wrapped_state, meta)
+      end
+
+      attr_reader :default_strategy
+
+      def continue?
+        !(error? || halted?)
+      end
+
+      def halted?
+        !!bare_state[:halted]
+      end
+
+      def final
+        Final.new(wrapped_state, meta, self.class)
+      end
+
+      def apply_validations(validations)
+        return self if error?
+
+        wrapped_state = self.class.validate(self.wrapped_state, validations)
+        self.class.send :new, wrapped_state, default_strategy, meta
+      end
+
+      def merge_error(error, action)
+        return wrapped_state if error?
+
+        wrapped_state = self.class.wrap_error_with_bare_state(error, {})
+        process_wrapped_result(wrapped_state, action, trace: true, validate: false)
+      end
+
+      def normalize_data(normalizer)
+        wrapped_state = normalize(normalizer)
+        self.class.send :new, wrapped_state, default_strategy, meta
+      end
+
+      def process_bare_result(bare_result, action, trace:, validate:)
+        process_result(action, trace, validate) do |strategy, action_name|
+          self.class.map_unwrappable_state(wrapped_state) do |bare_state|
+            self.class.merge_bare_result(bare_state, bare_result, strategy, action_name)
+          end
+        end
+      end
+
+      def process_wrapped_result(wrapped_result, action, trace:, validate:)
+        process_result(action, trace, validate) do |strategy, action_name|
+          if wrapped_result.nil?
+            raise Fatal::UnexpectedNil, action_name if strategy == :update
+
+            wrapped_state
+          else
+            raise Fatal::BadActionReturn.new(action_name, wrapped_result) unless self.class.canonical?(wrapped_result)
+
+            self.class.flat_map_unwrappable_state(wrapped_state) do |bare_state|
+              self.class.map_unwrappable_state(wrapped_result) do |bare_result|
+                self.class.merge_bare_result(bare_state, bare_result, strategy, action_name)
+              end
+            end
+          end
+        end
+      end
+
+      def state_class
+        self.class
+      end
+
+      private
+
+      def process_result(action, trace, validate, &block)
+        meta = trace ? self.meta.add(action.name) : self.meta
+
+        strategy = action.state_transition_strategy || default_strategy
+        wrapped_result = block.call(strategy, action.name)
+        validations = action.validations if validate
+        wrapped_state = self.class.validate(wrapped_result, validations)
+
+        self.class.send :new, wrapped_state, default_strategy, meta
+      end
+
+      def normalize(normalizer)
+        self.class.map_unwrappable_state(wrapped_state) do |bare_state|
+          normalized = normalizer.normalize(bare_state)
+          next normalized unless error?
+
+          self.class.wrap_error_with_bare_state(self.class.unwrap_error(wrapped_state), normalized)
+        end
+      end
+    end
+  end
+end

data/lib/workflow_template/state/meta.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module WorkflowTemplate
+  module State
+    class Meta
+      module Null
+        def self.add(*)
+          self
+        end
+
+        def self.trace
+          nil
+        end
+
+        freeze
+      end
+
+      attr_reader :trace
+
+      def self.instance(trace)
+        trace ? new : Null
+      end
+
+      private_class_method :new
+
+      def initialize(trace: [])
+        @trace = trace.freeze
+      end
+
+      def add(name)
+        self.class.send :new, trace: [*@trace, name]
+      end
+    end
+  end
+end

data/lib/workflow_template/state/normalizer.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module WorkflowTemplate
+  module State
+    class Normalizer
+      attr_reader :keys
+
+      def initialize(keys)
+        @keys = keys&.map(&:to_sym).freeze
+        freeze
+      end
+
+      def normalize(hash)
+        return hash if keys.nil?
+
+        keys.each_with_object({}) do |key, normalized|
+          normalized[key] = hash[key]
+        end.freeze
+      end
+
+      private_class_method :new
+
+      def self.instance(keys = nil)
+        return null_object if keys.nil?
+
+        new keys
+      end
+
+      def self.null_object
+        @null_object ||= new(nil)
+      end
+    end
+  end
+end

data/lib/workflow_template/state/validation.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative '../validation/result/success'
+
+module WorkflowTemplate
+  module State
+    module Validation
+      def self.validate(data, validations)
+        case validations
+        when Array then validate_multiple(data, validations)
+        else validations.call(data)
+        end
+      end
+
+      def self.validate_multiple(data, validations)
+        validations.reduce(WorkflowTemplate::Validation::Result::Success) do |result, validation|
+          break result unless result.success?
+
+          validation.call(data)
+        end
+      end
+
+      def self.applicable?(validations)
+        case validations
+        when nil then false
+        when Array then !validations.empty?
+        else true
+        end
+      end
+    end
+  end
+end

data/lib/workflow_template/state.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative 'state/intermediate'
+
+module WorkflowTemplate
+  module State
+    STRATEGIES = %i[merge update].freeze
+
+    def self.normalize_transition_strategy(strategy)
+      strategy = strategy.to_sym
+      raise Error, "Unimplemented strategy: '#{strategy}'" unless STRATEGIES.include?(strategy)
+
+      strategy
+    end
+
+    def self.state_class(adapter)
+      state_classes[adapter] ||= Class.new do
+        include State::Intermediate
+        extend State::ClassMethods
+
+        raise Error, "Invalid adapter: #{adapter}" unless State.valid_adapter?(adapter)
+
+        include adapter::InstanceMethods
+        extend adapter::ClassMethods
+
+        private_class_method :new
+      end
+    end
+
+    def self.valid_adapter?(adapter)
+      adapter.constants.include?(:InstanceMethods) &&
+        adapter::InstanceMethods.included_modules.include?(Adapter::Abstract::InstanceMethods) &&
+        adapter.constants.include?(:ClassMethods) &&
+        adapter::ClassMethods.included_modules.include?(Adapter::Abstract::ClassMethods)
+    end
+
+    def self.state_classes
+      @state_classes ||= {}
+    end
+  end
+end

data/lib/workflow_template/validation/adapter/abstract/builder.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative '../../builder/error'
+require_relative '../../evaluation'
+
+module WorkflowTemplate
+  module Validation
+    module Adapter
+      module Abstract
+        class Builder
+          Error = Validation::Builder::Error
+
+          def initialize(proxy)
+            @proxy = proxy
+          end
+
+          def validate
+            self
+          end
+
+          private
+
+          attr_reader :proxy
+        end
+      end
+    end
+  end
+end