flows 0.2.0 → 0.6.0

data/lib/flows/contract/case_eq.rb

@@ -0,0 +1,43 @@
+module Flows
+  class Contract
+    # Makes a contract from provided object's case equality check.
+    #
+    # @example String contract
+    #     string_check = Flows::Contract::CaseEq.new(String)
+    #
+    #     string_check.check(111)
+    #     # => Flows::Result::Err.new('must match `String`')
+    #
+    #     string_check === 'sdfdsfsd'
+    #     # => true
+    #
+    # @example Integer contract with custom error message
+    #     int_check = Flows::Contract::CaseEq.new(Integer, 'must be an integer')
+    #
+    #     int_check.check('111')
+    #     # => Flows::Result::Err.new('must be an integer')
+    #
+    #     string_check === 'sdfdsfsd'
+    #     # => true
+    class CaseEq < Contract
+      # @param object [#===] object with case equality
+      # @param error_message [String] you may override default error message
+      def initialize(object, error_message = nil)
+        @object = object
+        @error_message = error_message
+      end
+
+      # @see Contract#check!
+      def check!(other)
+        unless @object === other
+          value_error =
+            @error_message ||
+            "must match `#{@object.inspect}`, but has class `#{other.class.inspect}` and value `#{other.inspect}`"
+          raise Error.new(other, value_error)
+        end
+
+        true
+      end
+    end
+  end
+end

data/lib/flows/contract/compose.rb

@@ -0,0 +1,77 @@
+module Flows
+  class Contract
+    # Allows to combine two or more contracts.
+    #
+    # From type system perspective - this composition is intersection of types.
+    # It means that value passes contract if it passes each particular contract in a composition.
+    #
+    # ## Composition and Transform Laws
+    #
+    # _Golden rule:_ don't use contracts with transformations in composition if you can.
+    # In the most cases you can compose contracts without transformations
+    # and apply one transformation to composite contract.
+    #
+    # Composition of contracts' transformations MUST obey Transform Laws (see {Contract} documentation for details).
+    # To achieve this each particular transform MUST obey following additional laws:
+    #
+    #     # let `c` be a contract composition
+    #
+    #     # 1. each transform should not leave composite type
+    #     #
+    #     # for any `x` valid for composite type
+    #     c.check!(x) == true
+    #     # and for any contract `c_i` from composition:
+    #     c.check!(c_i.transform!(x)) == true
+    #
+    #     # 2. tranforms can be applied in any order
+    #     #
+    #     # for any `x` valid for composite type
+    #     c.check!(x) == true
+    #     # for any two contracts `c_i` and `c_j` from composition:
+    #     c_i(c_j(x)) == c_j(c_i(x))
+    #
+    # Why do we need the first law?
+    # To prevent situations when original value matches composite type,
+    # but transformed value doesn't. Example:
+    #
+    #     Flows::Contract.make do
+    #       compose(
+    #         transform(either(String, Symbol), &:to_sym),
+    #         String
+    #       )
+    #     end
+    #
+    # Second laws makes composition of transforms to obey 2nd transform law.
+    # Example of correct composable transforms:
+    #
+    #     Flows::Contract.make do
+    #       compose(
+    #         transform(String, &:strip),
+    #         transform(String, &:trim)
+    #       )
+    #     end
+    #
+    # Formal proof is based on [this theorem proof](https://math.stackexchange.com/questions/600978/equivalence-relation-composition-problem).
+    class Compose < Contract
+      # @param contracts [Array<Contract, Object>] contract list. Non-contract elements will be wrapped with {CaseEq}.
+      def initialize(*contracts)
+        raise 'Contract list must not be empty' if contracts.length.zero?
+
+        @contracts = contracts.map(&method(:to_contract))
+      end
+
+      # @see Contract#check!
+      def check!(other)
+        @contracts.each { |con| con.check!(other) }
+        true
+      end
+
+      # @see Contract#transform!
+      def transform!(other)
+        @contracts.reduce(other) do |value, con|
+          con.transform!(value)
+        end
+      end
+    end
+  end
+end

data/lib/flows/contract/either.rb

@@ -0,0 +1,53 @@
+module Flows
+  class Contract
+    # Allows to combine two or more contracts with "or" logic.
+    #
+    # First matching contract from provided list will be used.
+    #
+    # @example
+    #     str_or_sym = Flows::Contract::Either.new(String, Symbol)
+    #
+    #     str_or_sym === 'AAA'
+    #     # => true
+    #
+    #     str_or_sym === :AAA
+    #     # => true
+    #
+    #     str_or_sym === 111
+    #     # => false
+    class Either < Contract
+      # @param contracts [Array<Contract, Object>] contract list. Non-contract elements will be wrapped with {CaseEq}.
+      def initialize(*contracts)
+        raise 'Contract list must not be empty' if contracts.length.zero?
+
+        @contracts = contracts.map(&method(:to_contract))
+      end
+
+      # @see Contract#check!
+      def check!(other)
+        errors = @contracts.each_with_object([]) do |con, errs|
+          result = con.check(other)
+
+          return true if result.ok?
+
+          errs << result.error
+        end
+
+        raise Error.new(other, errors.join("\nOR "))
+      end
+
+      # @see Contract#transform!
+      def transform!(other)
+        errors = @contracts.each_with_object([]) do |con, errs|
+          result = con.transform(other)
+
+          return result.unwrap if result.ok?
+
+          errs << result.error
+        end
+
+        raise Error.new(other, errors.join("\nOR "))
+      end
+    end
+  end
+end

data/lib/flows/contract/error.rb

@@ -0,0 +1,24 @@
+module Flows
+  class Contract
+    # Class for {Type} errors.
+    class Error < ::Flows::Error
+      attr_reader :value, :value_error
+
+      # @param value [Object] checked value
+      # @param value_error [String] error message
+      def initialize(value, value_error)
+        @value = value
+        @value_error = value_error
+      end
+
+      def message
+        [
+          'type check failed for:',
+          "    `#{@value.inspect}`",
+          "---\n",
+          @value_error
+        ].join("\n")
+      end
+    end
+  end
+end

data/lib/flows/contract/hash.rb

@@ -0,0 +1,75 @@
+module Flows
+  class Contract
+    # Contract for Ruby `Hash` with specified contracts for keys and values.
+    #
+    # If key contract has transformation - Hash keys will be transformed.
+    #
+    # If value contract has transformation - Hash values will be transformed.
+    #
+    # @example
+    #     sym_int_hash = Flows::Contract::Hash.new(Symbol, Integer)
+    #
+    #     sym_int_hash === { a: 1, b: 2 }
+    #     # => true
+    #
+    #     sym_int_hash === { a: 1, b: 'BBB' }
+    #     # => true
+    class Hash < Contract
+      # Stop search for a new type mismatch in keys or values
+      # if CHECK_LIMIT errors already found.
+      #
+      # Applied separately for keys and values.
+      CHECK_LIMIT = 10
+
+      HASH_TYPE = CaseEq.new(::Hash)
+
+      # @param key_contract [Contract, Object] contract for keys, non-contract values will be wrapped with {CaseEq}
+      # @param value_contract [Contract, Object] contract for values, non-contract values will be wrapped with {CaseEq}
+      def initialize(key_contract, value_contract)
+        @key_contract = to_contract(key_contract)
+        @value_contract = to_contract(value_contract)
+      end
+
+      def check!(other)
+        HASH_TYPE.check!(other)
+
+        unless other.keys.all?(&@key_contract) && other.values.all?(&@value_contract)
+          value_error = report_error(other)
+          raise Error.new(other, value_error)
+        end
+
+        true
+      end
+
+      def transform!(other)
+        check!(other)
+
+        other
+          .transform_keys { |key| @key_contract.transform!(key) }
+          .transform_values { |value| @value_contract.transform!(value) }
+      end
+
+      private
+
+      def report_error(other)
+        (invalid_key_errors(other) + invalid_value_errors(other)).join("\n")
+      end
+
+      def invalid_key_errors(other)
+        other.keys.reject(&@key_contract)[0..CHECK_LIMIT].map do |key|
+          key_error = @key_contract.check(key).error
+
+          merge_nested_errors("hash key `#{key.inspect}` is invalid:", key_error)
+        end
+      end
+
+      def invalid_value_errors(other)
+        other.values.reject(&@value_contract)[0..CHECK_LIMIT].map do |value|
+          value_error = @value_contract.check(value).error
+
+          merge_nested_errors("hash value `#{value.inspect}` is invalid:", value_error)
+        end
+      end
+    end
+  end
+end

data/lib/flows/contract/hash_of.rb

@@ -0,0 +1,70 @@
+module Flows
+  class Contract
+    # Contract for Ruby `Hash` with specified structure.
+    #
+    # Hash can have extra keys. Extra keys will be removed after transform.
+    # Underlying contracts' transforms will be applied to correspond values.
+    #
+    # @example
+    #     point_type = Flows::Contract::HashOf.new(x: Numeric, y: Numeric)
+    #
+    #     point_type === { x: 1, y: 2.0 }
+    #     # => true
+    #
+    #     point_type === { x: 1, y: 2.0, name: 'Petr' }
+    #     # => true
+    #
+    #     point_type.cast(x: 1, y: 2.0, name: 'Petr').unwrap
+    #     # => { x: 1, y: 2.0 }
+    #
+    #     point_type.check({ x: 1, name: 'Petr' })
+    #     # => Flows::Result::Error.new('missing key `:y`')
+    #
+    #     point_type.check({ x: 1, y: 'Vasya' })
+    #     # => Flows::Result::Error.new('key `:y` has an invalid value: must match `Numeric`')
+    class HashOf < Contract
+      HASH_CONTRACT = CaseEq.new(::Hash)
+
+      def initialize(shape = {})
+        @shape = shape.transform_values(&method(:to_contract))
+      end
+
+      def check!(other)
+        HASH_CONTRACT.check!(other)
+
+        errors = check_shape(other)
+
+        raise Error.new(other, errors.join("\n")) if errors.any?
+
+        true
+      end
+
+      def transform!(other)
+        check!(other)
+
+        other
+          .slice(*@shape.keys)
+          .map { |key, value| [key, @shape[key].transform!(value)] }
+          .to_h
+      end
+
+      private
+
+      # :reek:DuplicateMethodCall
+      def check_shape(other)
+        @shape.each_with_object([]) do |(key, type), errors|
+          unless other.key?(key)
+            errors << "missing hash key `#{key.inspect}`"
+            next
+          end
+
+          result = type.check(other[key])
+
+          if result.err?
+            errors << merge_nested_errors("hash key `#{key.inspect}` has an invalid assigned value:", result.error)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/flows/contract/helpers.rb

@@ -0,0 +1,22 @@
+require 'forwardable'
+
+module Flows
+  class Contract
+    # Shortcuts for contract creation.
+    module Helpers
+      extend Forwardable
+
+      def_delegator CaseEq, :new, :case_eq
+      def_delegator Predicate, :new, :predicate
+
+      def_delegator Transformer, :new, :transformer
+      def_delegator Compose, :new, :compose
+      def_delegator Either, :new, :either
+
+      def_delegator Flows::Contract::Hash, :new, :hash
+      def_delegator HashOf, :new, :hash_of
+      def_delegator Flows::Contract::Array, :new, :array
+      def_delegator Tuple, :new, :tuple
+    end
+  end
+end

data/lib/flows/contract/predicate.rb

@@ -0,0 +1,34 @@
+module Flows
+  class Contract
+    # Makes a contract from 1-argument lambda.
+    #
+    # Such lambdas works like [predicates](https://en.wikipedia.org/wiki/Predicate_(mathematical_logic)).
+    #
+    # @example
+    #     positive_check = Flows::Contract::Predicate.new 'must be a positive integer' do |x|
+    #       x.is_a?(Integer) && x > 0
+    #     end
+    #
+    #     positive_check === 10
+    #     # => true
+    #
+    #     positive_check === -100
+    #     # => false
+    class Predicate < Contract
+      # @param error_message error message if check fails
+      # @yield [object] lambda to wrap into a contract
+      # @yieldreturn [Boolean] lambda should return a boolean
+      def initialize(error_message, &block)
+        @error_message = error_message
+        @block = block
+      end
+
+      # @see Contract#check!
+      def check!(other)
+        raise Error.new(other, @error_message) unless @block === other
+
+        true
+      end
+    end
+  end
+end

data/lib/flows/contract/transformer.rb

@@ -0,0 +1,50 @@
+module Flows
+  class Contract
+    # Adds transformation to an existing contract.
+    #
+    # If original contract already has a transform -
+    # final transformation will be composition of original and new one.
+    #
+    # You MUST obey Transformation Laws (see {Contract} documentation for details).
+    #
+    # @example Upcase strings
+    #     up_str = Flows::Contract::Transformer.new(String) { |str| str.upcase }
+    #
+    #     up_str.transform!('megatron')
+    #     # => 'MEGATRON'
+    #
+    #     up_str.transform(:megatron).error
+    #     # => 'must match `String`'
+    #
+    # @example Strip and upcase strings
+    #     strip_str =  Flows::Contract::Transformer.new(String, &:strip)
+    #     up_stip_str = Flows::Contract::Transformer.new(strip_str, &:upcase)
+    #
+    #     up_str.transform!('   megatron   ')
+    #     # => 'MEGATRON'
+    #
+    #     up_str.cast(:megatron).error
+    #     # => 'must match `String`'
+    class Transformer < Contract
+      # @param contract [Contract, Object] in case of non-contract argument {CaseEq} is automatically applied.
+      # @yield [object] transform implementation
+      # @yieldreturn [object] result of transform. Must obey transformation laws.
+      def initialize(contract, &transform_proc)
+        @contract = to_contract(contract)
+        @transform = transform_proc
+      end
+
+      # @see Contract#check!
+      def check!(other)
+        @contract.check!(other)
+      end
+
+      # @see Contract#transform!
+      def transform!(other)
+        @transform.call(
+          @contract.transform!(other)
+        )
+      end
+    end
+  end
+end