linearly 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: eac2749b4aad79a7f0a3720eb59024d1b1761747
+  data.tar.gz: 920e5ac7f405ac7326d439a7815c18ce353b3795
+SHA512:
+  metadata.gz: f9e00e9d2d3064c3cf2934c080a77c43643e2c4375ce92bb335c45895502ab938b3021f0285a9470be171195db4e8a7a916cbb3aa48309a40f2e27b5573c5538
+  data.tar.gz: 622bde992eacf7a3c30bf2a0cfaae44fc0462e380b21038a4b56f24da010bb62e7b8d10033640cb1fd0b8d192b1d0783c2af18eb8b7e002f7d9c8c312f0fb06a

data/lib/linearly/errors/broken_contract.rb

@@ -0,0 +1,80 @@
+require 'forwardable'
+
+# rubocop:disable Metrics/LineLength
+
+module Linearly
+  module Errors
+    # {BrokenContract} is what happens when inputs or outputs for a {Step} do
+    # not match expectations.
+    # @abstract
+    class BrokenContract < RuntimeError
+      extend Forwardable
+
+      # Input/output validation failures
+      #
+      # @return [Hash<Symbol, Validation::Failure>]
+      # @api public
+      # @example
+      #   err = Linearly::Errors::Inputs.new(
+      #     key: Linearly::Validation::Failure::Missing.instance,
+      #   )
+      #   err.failures
+      #   => {:key => [missing]}
+      attr_reader :failures
+
+      # @!method keys
+      # @return [Array<Symbol>]
+      # @see https://docs.ruby-lang.org/en/2.0.0/Hash.html#method-i-keys Hash#keys
+      # @api public
+      # @example
+      #   err = Linearly::Errors::BrokenContract::Inputs.new(
+      #     key: Linearly::Validation::Failure::Missing.instance,
+      #   )
+      #   err.keys
+      #   => [:key]
+      def_delegators :failures, :keys
+
+      # Constructor for a {BrokenContract} error
+      #
+      # @param failures [Hash<Symbol, Validation::Failure>]
+      #
+      # @api public
+      # @example
+      #   Linearly::Errors::BrokenContract::Inputs.new(
+      #     key: Linearly::Validation::Failure::Missing.instance,
+      #   )
+      #   => #<Linearly::Errors::BrokenContract::Inputs:
+      #        failed input expectations: [key]>
+      def initialize(failures)
+        @failures = failures
+        super("#{copy}: [#{keys.join(', ')}]")
+      end
+
+      # {Inputs} means a {BrokenContract} on inputs.
+      class Inputs < BrokenContract
+        private
+
+        # Copy for the error message
+        #
+        # @return [String]
+        # @api private
+        def copy
+          'failed input expectations'
+        end
+      end # class Inputs
+
+      # {Outputs} means a {BrokenContract} on outputs.
+      class Outputs < BrokenContract
+        private
+
+        # Copy for the error message
+        #
+        # @return [String]
+        # @api private
+        def copy
+          'failed output expectations'
+        end
+      end # class Outputs
+    end # class BrokenContract
+  end # module Errors
+end # module Linearly

data/lib/linearly/errors/state_not_returned.rb

@@ -0,0 +1,29 @@
+module Linearly
+  module Errors
+    # {StateNotReturned} is an error that is getting thrown when one of {Step}s
+    # in the {Flow} does not return an instance of +Statefully::State+.
+    # @api public
+    class StateNotReturned < RuntimeError
+      # Value that caused the error
+      #
+      # @return [Object]
+      # @api public
+      # @example
+      #   Linearly::Errors::StateNotReturned.new('surprise').value
+      #   => "surprise"
+      attr_reader :value
+
+      # Constructor for the {StateNotReturned} class
+      #
+      # @param value [Object]
+      #
+      # @api public
+      # @example
+      #   Linearly::Errors::StateNotReturned.new('surprise')
+      def initialize(value)
+        super("#{value.class.name} is not a Statefully::State")
+        @value = value
+      end
+    end # class StateNotReturned
+  end # module Errors
+end # module Linearly

data/lib/linearly/flow.rb

@@ -0,0 +1,144 @@
+require 'forwardable'
+
+module Linearly
+  class Flow
+    extend Forwardable
+    include Mixins::Reducer
+
+    # @!method call(state)
+    #   Validate the input state and run steps as long as it's a +Success+
+    #
+    #   @param [Statefully::State] state
+    #
+    #   @return [Statefully::State]
+    #   @api public
+    #   @example
+    #     flow = Linearly::Flow.new(
+    #       Users::Find,
+    #       Users::AddRole.new(:admin),
+    #       Users::Save,
+    #     )
+    #     flow.call(Statefully::State.create(user_id: params[:id]))
+    #
+    # @!method inputs
+    #   Inputs required for the {Flow}
+    #
+    #   @return [Hash<Symbol, TrueClass>]
+    #   @api public
+    #   @example
+    #     Linearly::Flow.new(Users::Find).inputs
+    #     => {user_id: true}
+    #
+    # @!method outputs
+    #   Outputs provided by the {Flow}
+    #
+    #   @return [Hash<Symbol, TrueClass>]
+    #   @api public
+    #   @example
+    #     Linearly::Flow.new(Users::Find).outputs
+    #     => {user: true}
+    def_delegators :@contract, :inputs, :outputs
+
+    # Constructor for the {Flow}
+    #
+    # @param steps [Array<Step>] array of things that implement the +Step+
+    #        interface (+call+, +inputs+ and +outputs+ methods).
+    #
+    # @api public
+    # @example
+    #   flow = Linearly::Flow.new(
+    #     Users::Find,
+    #     Users::AddRole.new(:admin),
+    #     Users::Save,
+    #   )
+    def initialize(*steps)
+      @steps = steps
+      @contract = Contract.new(steps)
+    end
+
+    # Convenience method to join +Step+s into one {Flow}
+    #
+    # @param other [Step]
+    #
+    # @return [Flow]
+    # @api public
+    # @example
+    #   flow =
+    #     Users::Find
+    #     .>> Users::Update
+    #     .>> Users::Save
+    def >>(other)
+      Flow.new(other, *@steps)
+    end
+
+    private
+
+    # Steps to be ran by the {Flow}
+    #
+    # @return [Array<Step>]
+    # @api private
+    def steps
+      [
+        Validation::Inputs.new(inputs),
+        *@steps.map(&Runner.method(:new)),
+        Validation::Outputs.new(outputs),
+      ]
+    end
+
+    # {Contract} is a companion for the {Flow}, providing it with logic for
+    # properly determining required +inputs+ and expected +outputs+.
+    class Contract
+      extend Forwardable
+
+      # Inputs required for the {Flow}
+      #
+      # @return [Hash<Symbol, TrueClass>]
+      # @api private
+      attr_reader :inputs
+
+      # Outputs provided by the {Flow}
+      #
+      # @return [Hash<Symbol, TrueClass>]
+      # @api private
+      attr_reader :outputs
+
+      # Constructor for the {Contract}
+      #
+      # @param steps [Array<Step>] array of things that implement the +Step+
+      #        interface (+call+, +inputs+ and +outputs+ methods).
+      #
+      # @api private
+      def initialize(steps)
+        @steps = steps
+        @inputs = {}
+        @outputs = {}
+        build
+      end
+
+      private
+
+      # Figure out inputs required and outputs provided by the {Flow}
+      #
+      # @return [Array] irrelevant
+      # @api private
+      def build
+        @steps.each(&method(:process))
+        [@inputs, @outputs].map(&:freeze)
+      end
+
+      # Process a single step
+      #
+      # @param step [Step]
+      #
+      # @return [Hash] irrelevant
+      # @api private
+      def process(step)
+        step.inputs.each do |key, val|
+          @inputs[key] = val unless @inputs.key?(key) || @outputs.key?(key)
+        end
+        @outputs.merge!(step.outputs)
+      end
+    end # class Contract
+    private_constant :Contract
+  end # class Flow
+end # module Linearly

data/lib/linearly/mixins/flow_builder.rb

@@ -0,0 +1,22 @@
+module Linearly
+  module Mixins
+    module FlowBuilder
+      # @!method self.>>(other)
+      # Convenience method to create a {Flow} from linked Steps
+      #
+      # @param other [Step] next step in the {Flow}
+      #
+      # @return [Flow]
+      # @api public
+      # @example
+      #   flow =
+      #     Users::Find
+      #     .>> Users::Update
+      #     .>> Users::Save
+      def >>(other)
+        Flow.new(self, other)
+      end
+    end # module FlowBuilder
+  end # module Mixins
+  private_constant :Mixins
+end # module Linearly

data/lib/linearly/mixins/reducer.rb

@@ -0,0 +1,32 @@
+require 'statefully'
+
+module Linearly
+  module Mixins
+    # {Reducer} is a mixin to include in all classes which need to run more than
+    # one step.
+    # @api private
+    module Reducer
+      # Keep calling steps as long as the state is successful
+      #
+      # This method reeks of :reek:TooManyStatements and :reek:FeatureEnvy.
+      #
+      # @param state [Statefully::State]
+      #
+      # @return [Statefully::State]
+      # @api private
+      def call(state)
+        steps.reduce(state) do |current, step|
+          break current if current.failed? || current.finished?
+          begin
+            next_state = step.call(current)
+          rescue StandardError => err
+            break current.fail(err)
+          end
+          next next_state if next_state.is_a?(Statefully::State)
+          current.fail(Errors::StateNotReturned.new(step))
+        end
+      end
+    end # module Reducer
+  end # module Mixins
+  private_constant :Mixins
+end # module Linearly

data/lib/linearly/runner.rb

@@ -0,0 +1,38 @@
+module Linearly
+  # {Runner} is a wrapper around a single step with inputs and outputs, which
+  # validates the inputs, runs the step, and validates the outputs.
+  # @api private
+  class Runner
+    include Mixins::Reducer
+
+    # Constructor for the {Runner} object
+    # @param step [Step] anything that implements the +Step+ interface
+    #        (+call+, +inputs+ and +outputs+ methods).
+    #
+    # @api private
+    def initialize(step)
+      @step = step
+    end
+
+    private
+
+    # Return the wrapped {Step}
+    #
+    # @return [Step]
+    # @api private
+    attr_reader :step
+
+    # Wrap the provided {Step} with input and output validation
+    #
+    # @return [Array<Step>]
+    # @api private
+    def steps
+      [
+        Validation::Inputs.new(step.inputs),
+        step,
+        Validation::Outputs.new(step.outputs),
+      ]
+    end
+  end # class Runner
+  private_constant :Runner
+end # module Linearly

data/lib/linearly/step/dynamic.rb

@@ -0,0 +1,50 @@
+module Linearly
+  module Step
+    module Dynamic
+      include Mixins::FlowBuilder
+
+      # Inputs for a step
+      #
+      # An invalid implementation is provided to ensure that a failure to
+      # override this method is not quietly caught as a StandardError.
+      #
+      # @return [Hash<Symbol, Expectation>]
+      # @api public
+      # @example
+      #   FindUser.new.inputs
+      #   => { user_id: Integer }
+      def inputs
+        raise NotImplementedError
+      end
+
+      # Outputs for a step
+      #
+      # An invalid implementation is provided to ensure that a failure to
+      # override this method is not quietly caught as a StandardError.
+      #
+      # @return [Hash<Symbol, Expectation>]
+      # @api public
+      # @example
+      #   FindUser.new.outputs
+      #   => { user: User }
+      def outputs
+        raise NotImplementedError
+      end
+
+      # User-defined logic for this +Step+
+      #
+      # An invalid implementation is provided to ensure that a failure to
+      # override this method is not quietly caught as a StandardError.
+      #
+      # @param _state [Statefully::State]
+      #
+      # @return [Statefully::State]
+      # @api public
+      # @example
+      #   FindUser.new.call(Statefully::State.create(user_id: 7))
+      def call(_state)
+        raise NotImplementedError
+      end
+    end # module Dynamic
+  end # module Step
+end # module Linearly

data/lib/linearly/step/static.rb

@@ -0,0 +1,120 @@
+module Linearly
+  module Step
+    # {Static} is a type of +Step+ whose operation solely depends on the content
+    # of the +State+ passed to its {.call} method. It's the best and most
+    # deterministic type of a +Step+, hence we provided a helper. Inheriting
+    # from {Static} will still require you to implement three methods: class
+    # +inputs+ and +outputs+ methods, and an instance +call+ method. What you
+    # get though is that your +call+ method does not need to take any parameters
+    # and will have access to the private +state+ instance variable. What's
+    # more, any unknown messages will be forwarded to +state+, so that your code
+    # can be shorter and more expressive. Also, you don't have to explicitly
+    # rescue exceptions - the static {.call} method will catch those and fail
+    # the +state+ accordingly.
+    class Static
+      extend Mixins::FlowBuilder
+
+      # Main entry point to {Step::Static}
+      #
+      # @param state [Statefully::State]
+      #
+      # @return [Statefully::State]
+      # @api public
+      # @example
+      #   class FindUser < Linearly::Step::Static
+      #     def self.inputs
+      #       { user_id: Integer }
+      #     end
+      #
+      #     def self.outputs
+      #       { user: User }
+      #     end
+      #
+      #     def call
+      #       succeed(user: User.find(user_id))
+      #     end
+      #   end # class FindUser
+      #   FindUser.call(Statefully::State.create(user_id: params[:id]))
+      def self.call(state)
+        new(state).call
+      rescue StandardError => err
+        state.fail(err)
+      end
+
+      # User-defined logic for this +Step+
+      #
+      # @return [Statefully::State]
+      # @api private
+      def call
+        raise NotImplementedError
+      end
+
+      # Inputs for a step
+      #
+      # @return [Hash<Symbol, Expectation>]
+      # @api public
+      # @example
+      #   FindUser.inputs
+      #   => { user_id: Integer }
+      def self.inputs
+        raise NotImplementedError
+      end
+
+      # Outputs for a step
+      #
+      # @return [Hash<Symbol, Expectation>]
+      # @api public
+      # @example
+      #   FindUser.outputs
+      #   => { user: User }
+      def self.outputs
+        raise NotImplementedError
+      end
+
+      private
+
+      # {State} received through the constructor
+      #
+      # @return [Statefully::State]
+      # @api private
+      attr_reader :state
+
+      # Constructor for the {Step::Static}
+      #
+      # @param state [Statefully::State]
+      # @api private
+      def initialize(state)
+        @state = state
+      end
+      private_class_method :new
+
+      # Dynamically pass unknown messages to the wrapped +State+
+      #
+      # @param name [Symbol|String]
+      # @param args [Array<Object>]
+      # @param block [Proc]
+      #
+      # @return [Object]
+      # @raise [NoMethodError]
+      # @api private
+      def method_missing(name, *args, &block)
+        state.send(name, *args, &block)
+      rescue NoMethodError
+        super
+      end
+
+      # Companion to `method_missing`
+      #
+      # This method reeks of :reek:BooleanParameter.
+      #
+      # @param name [Symbol|String]
+      # @param include_private [Boolean]
+      #
+      # @return [Boolean]
+      # @api private
+      def respond_to_missing?(name, include_private = false)
+        state.send(:respond_to_missing?, name, include_private)
+      end
+    end # class Static
+  end # module Step
+end # module Linearly