linearly 0.1.0

data/lib/linearly/validation.rb

@@ -0,0 +1,190 @@
+require 'singleton'
+
+module Linearly
+  # {Validation} provides a way to check inputs and outputs against a set of
+  # per-field expectations.
+  # @abstract
+  class Validation
+    # Constructor for a {Validation}
+    #
+    # @param expectations [Hash<Symbol, Expectation>] a hash of per-field
+    #        expectations. An expectation can be +true+ (just checking for field
+    #        presence), a class name (checking for value type) or a +Proc+
+    #        taking a value and returning a +Boolean+.
+    #
+    # @api private
+    def initialize(expectations)
+      @expectations =
+        expectations
+        .map { |key, expectation| [key, Expectation.to_proc(expectation)] }
+        .to_h
+    end
+
+    # Call validation with a {State}
+    #
+    # @param state [Statefully::State]
+    #
+    # @return [Statefully::State]
+    # @api private
+    def call(state)
+      Validator
+        .new(expectations, state)
+        .validate(error_class)
+    end
+
+    private
+
+    # Wrapped expectations
+    #
+    # @return [Hash<Symbol, Expectation>]
+    # @api private
+    attr_reader :expectations
+
+    # {Inputs} is a pre-flight {Validation} of {State} inputs
+    class Inputs < Validation
+      private
+
+      # Return associated error class
+      #
+      # @return [Class]
+      # @api private
+      def error_class
+        Errors::BrokenContract::Inputs
+      end
+    end # class Inputs
+
+    # {Inputs} is a post-flight {Validation} of {State} outputs
+    class Outputs < Validation
+      private
+
+      # Return associated error class
+      #
+      # @return [Class]
+      # @api private
+      def error_class
+        Errors::BrokenContract::Outputs
+      end
+    end # class Outputs
+
+    # {Validator} is a stateful helper applying expecations to a {State}
+    class Validator
+      # Constructor method for a {Validator}
+      #
+      # @param expectations [Hash<Symbol, Expectation>]
+      # @param state [Statefully::State]
+      #
+      # @api private
+      def initialize(expectations, state)
+        @expectations = expectations
+        @state = state
+      end
+
+      # Validate wrapped {State}, failing it with an error class if needed
+      #
+      # @param error_class [Class]
+      #
+      # @return [Statefully::State]
+      # @api private
+      def validate(error_class)
+        failures = invalid.merge(missing).freeze
+        return @state if failures.empty?
+        @state.fail(error_class.new(failures))
+      end
+
+      private
+
+      # Return the invalid fields
+      #
+      # @return [Hash<Field, Failure::Unexpected>]
+      # @api private
+      def invalid
+        @invalid ||= @expectations.map do |key, expectation|
+          next nil if missing.key?(key)
+          value = @state.fetch(key)
+          next nil if expectation.call(value)
+          [key, Failure::Unexpected.instance]
+        end.compact.to_h
+      end
+
+      # Return the missing fields
+      #
+      # @return [Hash<Field, Failure::Missing>]
+      # @api private
+      def missing
+        @missing ||=
+          @expectations
+          .keys
+          .reject { |key| @state.key?(key) }
+          .map    { |key| [key, Failure::Missing.instance] }
+          .to_h
+      end
+    end # class Validator
+    private_constant :Validator
+
+    # {Failure} is a representation of a problem encountered when validating a
+    # single {State} field.
+    class Failure
+      include Singleton
+
+      # Human-readable representation of the {Failure}
+      #
+      # @return [String]
+      # @api public
+      # @example
+      #   Linearly::Validation::Failure::Missing.instance.missing?
+      #   => [missing]
+      def inspect
+        "[#{self.class.name.split('::').last.downcase}]"
+      end
+
+      # {Unexpected} is a type of {Failure} when a field does not exists
+      class Missing < Failure
+        # Check if the field is missing
+        #
+        # @return [FalseClass]
+        # @api public
+        # @example
+        #   Linearly::Validation::Failure::Missing.instance.missing?
+        #   => true
+        def missing?
+          true
+        end
+      end # class Missing
+
+      # {Unexpected} is a type of {Failure} when a field exists, but its value
+      # does not match expectations.
+      class Unexpected < Failure
+        # Check if the field is missing
+        #
+        # @return [TrueClass]
+        # @api public
+        # @example
+        #   Linearly::Validation::Failure::Unexpected.instance.missing?
+        #   => true
+        def missing?
+          false
+        end
+      end # class Unexpected
+    end # class Failure
+
+    # {Expectation} is a helper module to turn various types of expectations
+    # into {Proc}s.
+    module Expectation
+      # Turn one of the supported expecation types into a Proc
+      #
+      # This method reeks of :reek:TooManyStatements.
+      #
+      # @param expectation [Symbol|Class|Proc]
+      #
+      # @return [Proc]
+      # @api private
+      def to_proc(expectation)
+        klass = expectation.class
+        return ->(value) { value.is_a?(expectation) } if klass == Class
+        return ->(_) { true } if klass == TrueClass
+        expectation
+      end
+      module_function :to_proc
+    end # module Expectation
+  end # class Validation
+end # module Linearly

data/lib/linearly/version.rb

@@ -0,0 +1,3 @@
+module Linearly
+  VERSION = '0.1.0'.freeze
+end # module Linearly

data/lib/linearly.rb

@@ -0,0 +1,12 @@
+require 'linearly/mixins/flow_builder'
+require 'linearly/mixins/reducer'
+require 'linearly/errors/broken_contract'
+require 'linearly/errors/state_not_returned'
+require 'linearly/flow'
+require 'linearly/runner'
+require 'linearly/step/dynamic'
+require 'linearly/step/static'
+require 'linearly/validation'
+require 'linearly/version'
+
+require 'statefully'

data/spec/dynamic_step.rb

@@ -0,0 +1,15 @@
+module Linearly
+  class DynamicStep
+    include Step::Dynamic
+
+    class Valid < DynamicStep
+      def inputs
+        {}
+      end
+
+      def outputs
+        {}
+      end
+    end # class Valid
+  end # class DynamicStep
+end # module Linearly

data/spec/errors/broken_contract_spec.rb

@@ -0,0 +1,29 @@
+require 'spec_helper'
+
+module Linearly
+  module Errors
+    describe BrokenContract do
+      let(:failures) do
+        {
+          missing: Validation::Failure::Missing.instance,
+          unexpected: Validation::Failure::Unexpected.instance,
+        }
+      end
+      let(:error) { described_class.new(failures) }
+
+      describe BrokenContract::Inputs do
+        let(:message) { 'failed input expectations: [missing, unexpected]' }
+
+        it { expect(error.message).to eq message }
+        it { expect(error.failures).to eq failures }
+      end # describe BrokenContract::Inputs
+
+      describe BrokenContract::Outputs do
+        let(:message) { 'failed output expectations: [missing, unexpected]' }
+
+        it { expect(error.message).to eq message }
+        it { expect(error.failures).to eq failures }
+      end # describe BrokenContract::Outputs
+    end # describe BrokenContract
+  end # module Errors
+end # module Linearly

data/spec/errors/state_not_returned_spec.rb

@@ -0,0 +1,13 @@
+require 'spec_helper'
+
+module Linearly
+  module Errors
+    describe StateNotReturned do
+      let(:value) { 'surprise!' }
+      let(:error) { described_class.new(value) }
+
+      it { expect(error.message).to eq 'String is not a Statefully::State' }
+      it { expect(error.value).to eq value }
+    end # describe StateNotReturned
+  end # module Errors
+end # module Linearly

data/spec/flow_spec.rb

@@ -0,0 +1,75 @@
+require 'spec_helper'
+
+module Linearly
+  describe Flow do
+    let(:step1_proc) { ->(state) { state.succeed(new_key: :new_val) } }
+    let(:step1) do
+      TestStep.new(
+        { key: String },
+        { new_key: Symbol },
+        step1_proc,
+      )
+    end
+    let(:step2) do
+      TestStep.new(
+        { other: Numeric },
+        {},
+        ->(state) { state.succeed },
+      )
+    end
+    let(:flow) { described_class.new(step1, step2) }
+
+    describe '#inputs' do
+      let(:inputs) { flow.inputs }
+
+      it { expect(inputs.length).to eq 2 }
+      it { expect(inputs.fetch(:key)).to eq String }
+      it { expect(inputs.fetch(:other)).to eq Numeric }
+    end # describe '#inputs'
+
+    describe '#outputs' do
+      let(:outputs) { flow.outputs }
+
+      it { expect(outputs.length).to eq 1 }
+      it { expect(outputs.fetch(:new_key)).to eq Symbol }
+    end # describe '#outputs'
+
+    describe '#>>' do
+      it { expect(flow.>>(step1)).to be_a Flow }
+    end # describe '#>>'
+
+    describe '#call' do
+      let(:state) { Statefully::State.create(**args) }
+      let(:result) { flow.call(state) }
+
+      context 'with correct input' do
+        let(:args) { { key: 'val', other: 7 } }
+
+        it { expect(result).to be_successful }
+        it { expect(result.history.length).to eq 3 }
+
+        context 'with a throwing step' do
+          let(:step1_proc) { ->(_) { raise 'Boom!' } }
+
+          it { expect(result).not_to be_successful }
+          it { expect(result.error).to be_a RuntimeError }
+        end # context 'with a throwing step'
+
+        context 'with a step not returning State' do
+          let(:step1_proc) { ->(_) { 'surprise!' } }
+
+          it { expect(result).not_to be_successful }
+          it { expect(result.error).to be_a Errors::StateNotReturned }
+        end # context 'with a step not returning State'
+      end # context 'with correct input'
+
+      context 'with missing initial state' do
+        let(:args) { { key: 'val' } }
+
+        it { expect(result).to be_failed }
+        it { expect(result.error).to be_a Errors::BrokenContract::Inputs }
+        it { expect(result.history.length).to eq 2 }
+      end # context 'with missing initial state'
+    end # describe '#call'
+  end # describe Flow
+end # module Linearly

data/spec/runner_spec.rb

@@ -0,0 +1,47 @@
+require 'spec_helper'
+
+module Linearly
+  describe Runner do
+    let(:state)    { Statefully::State.create(key: 'val') }
+    let(:behavior) { ->(state) { state.succeed(new_key: 'new_val') } }
+    let(:inputs)   { { key: true } }
+    let(:outputs)  { { new_key: true } }
+    let(:step)     { TestStep.new(inputs, outputs, behavior) }
+    let(:result)   { described_class.new(step).call(state) }
+
+    context 'when all goes well' do
+      it { expect(result).to be_successful }
+      it { expect(result).not_to be_finished }
+      it { expect(result.key).to eq 'val' }
+    end # context 'when all goes well'
+
+    shared_examples 'returns_error' do |error_class|
+      it { expect(result).not_to be_successful }
+      it { expect(result.error).to be_a error_class }
+    end # shared_examples 'returns_error'
+
+    context 'when input validation fails' do
+      let(:inputs) { { other: true } }
+
+      it_behaves_like 'returns_error', Errors::BrokenContract::Inputs
+    end # context 'when input validation fails'
+
+    context 'when step fails' do
+      let(:behavior) { ->(state) { state.fail(RuntimeError.new('Boom!')) } }
+
+      it_behaves_like 'returns_error', RuntimeError
+    end # context 'when step fails'
+
+    context 'when step finishes' do
+      let(:behavior) { ->(state) { state.finish } }
+
+      it { expect(result).to be_finished }
+    end # context 'when step finishes'
+
+    context 'when output validation fails' do
+      let(:outputs) { { other: true } }
+
+      it_behaves_like 'returns_error', Errors::BrokenContract::Outputs
+    end # context 'when output validation fails'
+  end # describe Runner
+end # module Linearly

data/spec/spec_helper.rb

@@ -0,0 +1,18 @@
+require 'bundler/setup'
+Bundler.setup
+
+require 'pry'
+
+if ENV['CI'] == 'true'
+  require 'simplecov'
+  SimpleCov.start { add_filter '/spec/' }
+
+  require 'codecov'
+  SimpleCov.formatter = SimpleCov::Formatter::Codecov
+end
+
+require 'linearly'
+
+require 'dynamic_step'
+require 'static_step'
+require 'test_step'

data/spec/static_step.rb

@@ -0,0 +1,15 @@
+module Linearly
+  class StaticStep < Step::Static
+    def self.inputs
+      { number: Integer }
+    end
+
+    def self.outputs
+      { string: String }
+    end
+
+    def call
+      succeed(string: (number + 1).to_s)
+    end
+  end # class StaticStep
+end # module Linearly

data/spec/step/dynamic_spec.rb

@@ -0,0 +1,29 @@
+require 'spec_helper'
+
+module Linearly
+  module Step
+    describe Dynamic do
+      let(:step) { DynamicStep.new }
+
+      describe '#inputs' do
+        it { expect { step.inputs }.to raise_error NotImplementedError }
+      end # describe '#inputs'
+
+      describe '#outputs' do
+        it { expect { step.outputs }.to raise_error NotImplementedError }
+      end # describe '#outputs'
+
+      describe '#call' do
+        let(:state) { Statefully::State.create }
+
+        it { expect { step.call(state) }.to raise_error NotImplementedError }
+      end # describe '#call'
+
+      describe '#>>' do
+        let(:step) { DynamicStep::Valid.new }
+
+        it { expect(step.>>(step)).to be_a Flow }
+      end # describe '#>>'
+    end # describe Dynamic
+  end # module Step
+end # module Linearly

data/spec/step/static_spec.rb

@@ -0,0 +1,52 @@
+require 'spec_helper'
+
+module Linearly
+  describe Step::Static do
+    let(:args)  { {} }
+    let(:state) { Statefully::State.create(**args) }
+
+    it { expect { described_class.inputs }.to raise_error NotImplementedError }
+    it { expect { described_class.outputs }.to raise_error NotImplementedError }
+
+    describe '.call' do
+      let(:result) { described_class.call(state) }
+
+      it { expect { result }.to raise_error NotImplementedError }
+    end # describe '.call'
+
+    describe 'implementation' do
+      subject { StaticStep }
+
+      describe '.>>' do
+        let(:flow) { subject.>>(subject) }
+
+        it { expect(flow).to be_a Flow }
+      end # describe '.>>'
+
+      describe '.call' do
+        let(:result) { subject.call(state) }
+
+        context 'with missing input' do
+          let(:args) { {} }
+
+          it { expect(result).not_to be_successful }
+          it { expect(result.error).to be_a NoMethodError }
+        end # context 'with missing input'
+
+        context 'with correct input' do
+          let(:args) { { number: 7 } }
+
+          it { expect(result).to be_successful }
+          it { expect(result.string).to eq '8' }
+        end # context 'with correct input'
+
+        context 'with incorrect input' do
+          let(:args) { { number: '7' } }
+
+          it { expect(result).not_to be_successful }
+          it { expect(result.error).to be_a TypeError }
+        end # context 'with incorrect input'
+      end # describe '.call'
+    end # describe 'implementation'
+  end # describe Step::Static
+end # module Linearly

data/spec/test_step.rb

@@ -0,0 +1,16 @@
+require 'forwardable'
+
+module Linearly
+  class TestStep
+    extend Forwardable
+
+    attr_reader :inputs, :outputs
+    def_delegators :@behavior, :call
+
+    def initialize(inputs, outputs, behavior)
+      @inputs = inputs
+      @outputs = outputs
+      @behavior = behavior
+    end
+  end # class TestStep
+end # module Linearly

data/spec/validation_spec.rb

@@ -0,0 +1,107 @@
+require 'spec_helper'
+
+module Linearly
+  describe Validation do
+    let(:validation) { described_class.new(expectations).call(state) }
+    let(:state)      { Statefully::State.create(key: 'val') }
+
+    shared_examples 'validation_fails' do |error_class|
+      it { expect(validation).to be_failed }
+      it { expect(validation.error).to be_a error_class }
+    end # shared_examples 'validation_fails'
+
+    shared_examples 'fails_when_missing_field' do |error_class|
+      let(:field) { :other }
+
+      it_behaves_like 'validation_fails', error_class
+
+      it { expect(validation.error).to be_a error_class }
+
+      context 'with failures' do
+        let(:failures) { validation.error.failures }
+
+        it { expect(validation.error.failures).to have_key(field) }
+        it { expect(validation.error.failures.fetch(field)).to be_missing }
+      end # context 'with failures'
+    end # shared_examples 'fails_when_missing_field'
+
+    shared_examples 'fails_with_unexpected_value' do |error_class|
+      it_behaves_like 'validation_fails', error_class
+
+      it { expect(validation.error).to be_a error_class }
+
+      context 'with failures' do
+        let(:failures) { validation.error.failures }
+
+        it { expect(validation.error.failures).to have_key(field) }
+        it { expect(validation.error.failures.fetch(field)).not_to be_missing }
+      end # context 'with failures'
+    end # shared_examples 'fails_with_unexpected_value'
+
+    shared_examples 'succeeds_and_returns_state' do
+      it { expect(validation).to be_successful }
+      it { expect(validation).to eq state }
+    end # shared_examples 'succeeds_and_returns_state'
+
+    shared_examples 'supports_presence_expectation' do |error_class|
+      let(:field)        { :key }
+      let(:expectations) { { field => true } }
+
+      it_behaves_like 'fails_when_missing_field', error_class
+      it_behaves_like 'succeeds_and_returns_state'
+    end # shared_examples 'supports_presence_expectation'
+
+    shared_examples 'supports_class_expectation' do |error_class|
+      let(:field)        { :key }
+      let(:klass)        { String }
+      let(:expectations) { { field => klass } }
+
+      it_behaves_like 'fails_when_missing_field', error_class
+
+      context 'when expectation is met (default)' do
+        it_behaves_like 'succeeds_and_returns_state'
+      end # context 'when expectation is met (default)'
+
+      context 'when expectation is not met' do
+        let(:klass) { Numeric }
+
+        it_behaves_like 'fails_with_unexpected_value', error_class
+      end # context 'when expectation is not met'
+    end # shared_examples 'supports_class_expectation'
+
+    shared_examples 'supports_proc_expectation' do |error_class|
+      let(:field)        { :key }
+      let(:klass)        { String }
+      let(:expectation)  { ->(val) { val.length == 3 } }
+      let(:expectations) { { field => expectation } }
+
+      it_behaves_like 'fails_when_missing_field', error_class
+
+      context 'when expectation is met (default)' do
+        it_behaves_like 'succeeds_and_returns_state'
+      end # context 'when expectation is met (default)'
+
+      context 'when expectation is not met' do
+        let(:expectation) { ->(val) { val.length == 4 } }
+
+        it_behaves_like 'fails_with_unexpected_value', error_class
+      end # context 'when expectation is not met'
+    end # shared_examples 'supports_proc_expectation'
+
+    describe Validation::Inputs do
+      error = Errors::BrokenContract::Inputs
+
+      it_behaves_like 'supports_presence_expectation', error
+      it_behaves_like 'supports_class_expectation', error
+      it_behaves_like 'supports_proc_expectation', error
+    end # describe Validation::Inputs
+
+    describe Validation::Outputs do
+      error = Errors::BrokenContract::Outputs
+
+      it_behaves_like 'supports_presence_expectation', error
+      it_behaves_like 'supports_class_expectation', error
+      it_behaves_like 'supports_proc_expectation', error
+    end # describe Validation::Outputs
+  end # describe Validation
+end # module Linearly