blood_contracts-ext 0.1.0

data/lib/blood_contracts/core/defineable_error.rb

@@ -0,0 +1,61 @@
+module BloodContracts::Core
+  # Meta class to define local errors in form of Tram::Policy::Errors
+  module DefineableError
+    # Concern with the helper to define custom Tram::Policy::Errors
+    module Concern
+      # @private
+      def inherited(other)
+        super
+        other.instance_variable_set(:@policy_scope, @policy_scope)
+      end
+
+      # Method that turns message into Tram::Policy::Errors object
+      #
+      # @param message [String, Symbol] (or translations key) for your
+      #   custom error
+      # @option tags [Hash] additional context for translations
+      # @option sub_scope [Symbol] is a customizable path to your
+      #   translation
+      # @return [Tram::Policy::Error]
+      #
+      def define_error(message, tags: {}, sub_scope: nil)
+        errors = Tram::Policy::Errors.new(scope: @policy_scope)
+        sub_scope = underscore(sub_scope || name)
+        message = [sub_scope, message].join(".").to_sym if message.is_a?(Symbol)
+        errors.add message, **tags
+        errors
+      end
+
+      # @private
+      private def underscore(string)
+        string.gsub(/([A-Z]+)([A-Z])/, '\1_\2')
+              .gsub(/([a-z])([A-Z])/, '\1_\2')
+              .gsub("__", "/")
+              .gsub("::", "/")
+              .gsub(/\s+/, "") # spaces are bad form
+              .gsub(/[?%*:|"<>.]+/, "") # reserved characters
+              .downcase
+      end
+    end
+
+    class << self
+      # Method that creates meta class for defining custom Tram::Policy::Errors
+      #
+      # @param policy_scope [Symbol] is a root for your I18n translations
+      # @return [Module]
+      #
+      def new(policy_scope)
+        m = Module.new do
+          def self.extended(other)
+            other.instance_variable_set(
+              :@policy_scope, instance_variable_get(:@policy_scope)
+            )
+          end
+        end
+        m.include(Concern)
+        m.instance_variable_set(:@policy_scope, policy_scope)
+        m
+      end
+    end
+  end
+end

data/lib/blood_contracts/core/exception_caught.rb

@@ -0,0 +1,33 @@
+module BloodContracts::Core
+  # Refinement type which holds exception as a value
+  class ExceptionCaught < ContractFailure
+    # Constructs refinement type around exception
+    #
+    # @param value [Exception] value which is wrapped inside the type
+    # @option context [Hash] shared context of types matching pipeline
+    #
+    def initialize(value = nil, context: Hash.new { |h, k| h[k] = {} }, **)
+      @errors = []
+      @context = context
+      @value = value
+      @context[:exception] = value
+    end
+
+    # Predicate, whether the data is valid or not
+    # (for the ExceptionCaught it is always False)
+    #
+    # @return [Boolean]
+    #
+    def valid?
+      false
+    end
+
+    # Reader for the exception caught
+    #
+    # @return [Exception]
+    #
+    def exception
+      @context[:exception]
+    end
+  end
+end

data/lib/blood_contracts/core/exception_handling.rb

@@ -0,0 +1,36 @@
+module BloodContracts::Core
+  # Concern to wrap matching process with exception handling
+  #
+  # @example Defines a type with automatic exception handling in form of types
+  #   class JsonType < ::BC::Refined
+  #     prepend ExceptionHandling
+  #
+  #     def match
+  #       @context[:parsed_json] = JSON.parse(value)
+  #       self
+  #     end
+  #   end
+  #
+  module ExceptionHandling
+    # Runs the matching process and returns an ExceptionCaught if
+    # StandardError happened inside match call
+    #
+    # @return [Refined]
+    #
+    def match
+      super
+    rescue StandardError => ex
+      exception(ex)
+    end
+
+    # Wraps the exception in refinement type
+    #
+    # @param exc [Exception] raised exception
+    # @option context [Hash] shared context of matching pipeline
+    # @return [ExceptionCaught]
+    #
+    def exception(exc, context: @context)
+      ExceptionCaught.new(exc, context: context)
+    end
+  end
+end

data/lib/blood_contracts/core/expected_error.rb

@@ -0,0 +1,16 @@
+module BloodContracts::Core
+  # Custom refinement type that converts the extracted data into
+  # Tram::Policy::Errors, could by used when the case is an error but
+  # you know how to deal with it inside application
+  class ExpectedError < Ext::Refined
+    # Generates an Tram::Policy::Errors message using the matching context
+    #
+    # @return [Tram::Policy::Errors]
+    def mapped
+      keys = self.class.extractors.keys
+      tags = Hash[keys.zip(@context.values_at(*keys))]
+      tags = @context if tags.empty?
+      self.class.define_error(:message, tags: tags)
+    end
+  end
+end

data/lib/blood_contracts/core/extractable.rb

@@ -0,0 +1,85 @@
+module BloodContracts::Core
+  # Concern that turns your refinement type into a coercer with validation
+  # delegated to Tram::Policy
+  module Extractable
+    # @private
+    def self.included(other_class)
+      other_class.extend(ClassMethods)
+    end
+
+    # DSL definition
+    module ClassMethods
+      # Configuration about how to extract data from the value, just
+      # list of context keys and methods
+      attr_reader :extractors
+
+      # Tram::Policy ancestor that will be used for validation
+      #
+      # @param [Class]
+      #
+      attr_accessor :policy
+
+      # @private
+      def inherited(child)
+        super
+        child.instance_variable_set(:@extractors, {})
+      end
+
+      # DSL to define which method to use to extract data from the value
+      #
+      # @param extractor_name [Symbol] key to store the extracted data in the
+      #   context
+      # @option method_name [Symbol] custom method name to use for extraction
+      # @return [Nothing]
+      #
+      def extract(extractor_name, method_name: extractor_name)
+        extractors[extractor_name] = [method_name]
+      end
+    end
+
+    # Turns matching process into 2 steps:
+    # - extraction of data from the value
+    # - validation using the policy_klass
+    #
+    # @return [Refined]
+    def match
+      extract!
+      policy_failure_match! || self
+    end
+
+    # Turns value into the hash of extracted data
+    #
+    # @return [Hash]
+    def mapped
+      keys = self.class.extractors.keys
+      Hash[keys.zip(@context.values_at(*keys))]
+    end
+
+    # Extracts data from the value
+    #
+    # @return [Nothing]
+    #
+    protected def extract!
+      self.class.extractors.each do |field, settings|
+        next if !context[field].nil? && !context[field].empty?
+
+        method_name, = *settings
+        context[field] = send(method_name.to_s)
+      end
+    end
+
+    # Validates extracted data using policy_klass
+    #
+    # @return [Refined, Nil]
+    #
+    protected def policy_failure_match!
+      return unless self.class.policy
+
+      policy_input = context.reduce({}) { |a, (k, v)| a.merge!(k.to_sym => v) }
+      policy_instance = self.class.policy[**policy_input]
+      return if policy_instance.valid?
+
+      failure(policy_instance.errors)
+    end
+  end
+end

data/lib/blood_contracts/core/map_value.rb

@@ -0,0 +1,45 @@
+module BloodContracts::Core
+  # Mapper in form of refinement type, transforms the value using mapper_klass
+  class MapValue < Refined
+    class << self
+      # Any callable object which you prefer to turn value into other form
+      #
+      # @param [Class, #call]
+      # @return [Class]
+      #
+      attr_accessor :mapper_klass
+
+      # Generates meta-class with predefined mapper_klass
+      #
+      # @param mapper_klass [Class, callable] callable object that will
+      #   transform the value
+      # @return [MapValue]
+      #
+      def with(mapper_klass)
+        type = Class.new(self)
+        type.mapper_klass = mapper_klass
+        type
+      end
+    end
+
+    # Always successful matching process which transforms the value and
+    # store it in the context
+    #
+    # @return [Refined]
+    #
+    def match
+      context[:mapper_input] = value
+      context[:mapped_value] =
+        self.class.mapper_klass.call(**context[:mapper_input])
+      self
+    end
+
+    # Mapped representation of the value
+    #
+    # @return [Object]
+    #
+    def mapped
+      match.context[:mapped_value]
+    end
+  end
+end

data/lib/blood_contracts/core/policy_failure.rb

@@ -0,0 +1,42 @@
+module BloodContracts::Core
+  # ContractFailure which holds errors in form of Tram::Policy::Errors
+  class PolicyFailure < ContractFailure
+    # Extends the type with ability to generate custom errors, to wrap and
+    # error message into Tram::Policy::Errors
+    extend DefineableError.new(:contracts)
+
+    # Builds an PolicyFailure, turns the errors into Tram::Policy::Errors
+    # if they are not, yet
+    #
+    # @param errors_per_type [Hash<Refined, Array<String,Symbol>>] map of
+    #   errors per type, each type could have a list of errors
+    # @option context [Hash] shared context of  matching pipeline
+    #
+    def initialize(errors_per_type = nil, context: {}, **)
+      sub_scope = context.delete(:sub_scope)
+      errors_per_type.to_h.transform_values! do |errors|
+        errors.map do |error|
+          next(error) if error.is_a?(Tram::Policy::Errors)
+          self.class.define_error(error, tags: context, sub_scope: sub_scope)
+        end
+      end
+      super
+    end
+
+    # Merged list of Tram::Policy::Errors after the matching run
+    #
+    # @return [Array<Tram::Policy::Errors>]
+    #
+    def policy_errors
+      @policy_errors ||= @value.values.flatten
+    end
+
+    # Merged list of Tram::Policy::Errors messages (or their translations)
+    #
+    # @return [Array<String>]
+    #
+    def messages
+      @messages ||= policy_errors.map(&:messages).flatten
+    end
+  end
+end

data/lib/blood_contracts/core/sum_policy_failure.rb

@@ -0,0 +1,9 @@
+module BloodContracts::Core
+  # Represents failure in Sum data matching
+  class SumPolicyFailure < PolicyFailure
+    # Custom accessor for policy errors in case of Ext::Sum types composition
+    def policy_errors
+      @policy_errors ||= @context[:sum_errors].map(&:policy_errors).flatten
+    end
+  end
+end

data/lib/blood_contracts/core/tuple_policy_failure.rb

@@ -0,0 +1,39 @@
+module BloodContracts::Core
+  # Represents failure in Tuple data matching
+  class TuplePolicyFailure < PolicyFailure
+    # Hash of attributes (name & type pairs)
+    #
+    # @return [Hash<String, Refined>]
+    #
+    def attributes
+      @context[:attributes]
+    end
+
+    # Subset of attributes which are invalid
+    #
+    # @return [Hash<String, PolicyFailure>]
+    #
+    def attribute_errors
+      attributes.select { |_name, type| type.invalid? }
+    end
+
+    # Subset of attributes which are invalid
+    #
+    # @return [Hash<String, PolicyFailure>]
+    #
+    def attribute_messages
+      attribute_errors.transform_values!(&:messages)
+    end
+
+    # Unpacked matching errors in form of a hash per attribute
+    #
+    # @return [Hash<String, PolicyFailure>]
+    #
+    def unpack_h
+      @unpack_h ||= attribute_errors.transform_values(&:unpack)
+    end
+    alias to_hash unpack_h
+    alias to_h unpack_h
+    alias unpack_attributes unpack_h
+  end
+end

data/lib/blood_contracts/ext/pipe.rb

@@ -0,0 +1,27 @@
+module BloodContracts::Core
+  module Ext
+    # Refinement types representation of Sum types composition, extended version
+    class Pipe < ::BC::Pipe
+      # Sets the default failure_klass to PolicyFailure, to use
+      # Tram::Policy::Errors for errors
+      self.failure_klass = PolicyFailure
+
+      # @private
+      def self.inherited(new_klass)
+        new_klass.failure_klass ||= failure_klass
+        super
+      end
+
+      # Generate an PolicyFailure from the error, also stores the
+      # additional scope for Tram::Policy::Errors in the context
+      #
+      # @param (see BC::Refined#failure)
+      # @return [PolicyFailure]
+      #
+      def failure(*, **)
+        @context[:sub_scope] = self.class.name
+        super
+      end
+    end
+  end
+end

data/lib/blood_contracts/ext/refined.rb

@@ -0,0 +1,59 @@
+module BloodContracts::Core
+  module Ext
+    # Refinement type exteneded with Extractable, ExceptionHandling and
+    # errors representation in form of Tram::Policy::Errors
+    class Refined < ::BC::Refined
+      # Adds ability to generate custom errors in form of Tram::Policy::Errors
+      extend DefineableError.new(:contracts)
+
+      # Adds extractors DSL
+      include Extractable
+
+      # Adds exception handling in form of refinment type
+      prepend ExceptionHandling
+
+      # Sets the default failure_klass to PolicyFailure, to use
+      # Tram::Policy::Errors for errors
+      self.failure_klass = PolicyFailure
+
+      class << self
+        # Compose types in a Sum check
+        # Sum passes data from type to type in parallel, only one type
+        # have to match
+        #
+        # @return [BC::Sum]
+        #
+        def or_a(other_type)
+          BC::Ext::Sum.new(self, other_type)
+        end
+
+        # Compose types in a Pipe check
+        # Pipe passes data from type to type sequentially
+        #
+        # @return [BC::Pipe]
+        #
+        def and_then(other_type)
+          BC::Ext::Pipe.new(self, other_type)
+        end
+
+        # @private
+        def inherited(new_klass)
+          new_klass.failure_klass ||= failure_klass
+          new_klass.prepend ExceptionHandling
+          super
+        end
+      end
+
+      # Generate an PolicyFailure from the error, also stores the
+      # additional scope for Tram::Policy::Errors in the context
+      #
+      # @param (see BC::Refined#failure)
+      # @return [PolicyFailure]
+      #
+      def failure(*, **)
+        @context[:sub_scope] = self.class.name
+        super
+      end
+    end
+  end
+end

data/lib/blood_contracts/ext/sum.rb

@@ -0,0 +1,29 @@
+module BloodContracts::Core
+  module Ext
+    # Refinement types representation of Sum types composition, extended version
+    class Sum < ::BC::Sum
+      # Sets the default failure_klass to PolicyFailure, to use
+      # Tram::Policy::Errors for errors
+      self.failure_klass = SumPolicyFailure
+
+      # @private
+      def self.inherited(new_klass)
+        new_klass.failure_klass ||= failure_klass
+        super
+      end
+
+      # Generate an PolicyFailure from the error, also stores the
+      # additional scope for Tram::Policy::Errors in the context.
+      # Also saves the Sum errors in the context
+      #
+      # @param (see BC::Refined#failure)
+      # @return [PolicyFailure]
+      #
+      def failure(*, **)
+        @context[:sum_errors] = @or_matches
+        @context[:sub_scope] = self.class.name
+        super
+      end
+    end
+  end
+end

data/lib/blood_contracts/ext/tuple.rb

@@ -0,0 +1,28 @@
+module BloodContracts::Core
+  module Ext
+    # Refinement types representation of Sum types composition, extended version
+    class Tuple < ::BC::Tuple
+      # Sets the default failure_klass to PolicyFailure, to use
+      # Tram::Policy::Errors for errors
+      self.failure_klass = TuplePolicyFailure
+
+      # @private
+      def self.inherited(new_klass)
+        new_klass.failure_klass ||= failure_klass
+        super
+      end
+
+      # Generate an PolicyFailure from the error, also stores the
+      # additional scope for Tram::Policy::Errors in the context.
+      # Also saves the Tuple error in the context[:attributes] by the :base key
+      #
+      # @param (see BC::Refined#failure)
+      # @return [PolicyFailure]
+      #
+      def failure(*, **)
+        @context[:sub_scope] = self.class.name
+        @context[:attributes].store(:base, super)
+      end
+    end
+  end
+end

data/lib/blood_contracts/ext.rb

@@ -0,0 +1,28 @@
+require "blood_contracts/core"
+require "tram-policy"
+
+# Top-level scope for BloodContracts toolset
+module BloodContracts
+  # Scope for refinement types & helpers for them
+  module Core
+    require_relative "core/defineable_error.rb"
+
+    require_relative "core/policy_failure.rb"
+    require_relative "core/tuple_policy_failure.rb"
+    require_relative "core/sum_policy_failure.rb"
+    require_relative "core/exception_caught.rb"
+    require_relative "core/exception_handling.rb"
+    require_relative "core/extractable.rb"
+
+    # Scope for extended refinement types
+    module Ext
+      require_relative "ext/refined.rb"
+      require_relative "ext/sum.rb"
+      require_relative "ext/pipe.rb"
+      require_relative "ext/tuple.rb"
+    end
+
+    require_relative "core/expected_error.rb"
+    require_relative "core/map_value.rb"
+  end
+end

data/spec/blood_contracts/ext/exception_caught_spec.rb

@@ -0,0 +1,50 @@
+RSpec.describe BloodContracts::Core::ExceptionCaught do
+  before do
+    module Test
+      class JsonType < BC::Refined
+        prepend BC::ExceptionHandling
+
+        def match
+          @context[:json_type_input] = value
+          @context[:parsed_json] = JSON.parse(@context[:json_type_input])
+          self
+        end
+      end
+    end
+  end
+
+  subject { Test::JsonType.match(value) }
+
+  context "when value is valid" do
+    let(:value) { '{"some": "thing"}' }
+    let(:payload) { { "some" => "thing" } }
+
+    it do
+      is_expected.to be_valid
+      expect(subject.context[:json_type_input]).to eq(value)
+      expect(subject.context[:parsed_json]).to match(payload)
+    end
+  end
+
+  context "when value is invalid" do
+    context "when value is a String" do
+      let(:value) { "nope, I'm not a JSON" }
+
+      it do
+        is_expected.to be_invalid
+        expect(subject.context[:json_type_input]).to eq(value)
+        expect(subject.exception).to match(kind_of(JSON::ParserError))
+      end
+    end
+
+    context "when value is a arbitrary object" do
+      let(:value) { Class.new }
+
+      it do
+        is_expected.to be_invalid
+        expect(subject.context[:json_type_input]).to eq(value)
+        expect(subject.exception).to match(kind_of(TypeError))
+      end
+    end
+  end
+end

data/spec/blood_contracts/ext/expected_error_spec.rb

@@ -0,0 +1,56 @@
+RSpec.describe BloodContracts::Core::ExpectedError do
+  before do
+    module Test
+      class PlainTextError < BC::ExpectedError
+        def match
+          @context[:parsed] ||= JSON.parse(value)
+        rescue JSON::ParserError
+          @context[:plain_text] = value.to_s
+          self
+        end
+      end
+
+      class JsonType < BC::Ext::Refined
+        def match
+          @context[:parsed] ||= JSON.parse(value)
+          self
+        end
+
+        def mapped
+          @context[:parsed]
+        end
+      end
+
+      Response = JsonType.or_a(PlainTextError)
+    end
+  end
+
+  subject { Test::Response.match(value) }
+
+  context "when value is a JSON" do
+    let(:value) { '{"name": "Andrew", "registered_at": "2019-01-01"}' }
+    let(:payload) do
+      { "name" => "Andrew", "registered_at" => "2019-01-01" }
+    end
+
+    it do
+      is_expected.to be_valid
+      is_expected.to match(kind_of(Test::JsonType))
+      expect(subject.unpack).to match(payload)
+    end
+  end
+
+  context "when value is a plain text" do
+    let(:value) { "Nothing found!" }
+    let(:error_messages) do
+      ["Service responded with a message: `#{value}`"]
+    end
+
+    it do
+      is_expected.to be_valid
+      expect(subject).to match(kind_of(Test::PlainTextError))
+      expect(subject.unpack).to match(kind_of(Tram::Policy::Errors))
+      expect(subject.unpack.messages).to match(error_messages)
+    end
+  end
+end