lithic 0.1.0.pre.alpha.4 → 0.1.0.pre.alpha.6

data/lib/lithic/internal/type/converter.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+module Lithic
+  module Internal
+    module Type
+      # rubocop:disable Metrics/ModuleLength
+      # @api private
+      module Converter
+        # rubocop:disable Lint/UnusedMethodArgument
+
+        # @api private
+        #
+        # @param value [Object]
+        #
+        # @param state [Hash{Symbol=>Object}] .
+        #
+        #   @option state [Boolean, :strong] :strictness
+        #
+        #   @option state [Hash{Symbol=>Object}] :exactness
+        #
+        #   @option state [Integer] :branched
+        #
+        # @return [Object]
+        def coerce(value, state:) = (raise NotImplementedError)
+
+        # @api private
+        #
+        # @param value [Object]
+        #
+        # @return [Object]
+        def dump(value)
+          case value
+          in Array
+            value.map { Lithic::Internal::Type::Unknown.dump(_1) }
+          in Hash
+            value.transform_values { Lithic::Internal::Type::Unknown.dump(_1) }
+          in Lithic::Internal::Type::BaseModel
+            value.class.dump(value)
+          else
+            value
+          end
+        end
+
+        # rubocop:enable Lint/UnusedMethodArgument
+
+        class << self
+          # @api private
+          #
+          # @param spec [Hash{Symbol=>Object}, Proc, Lithic::Internal::Type::Converter, Class] .
+          #
+          #   @option spec [NilClass, TrueClass, FalseClass, Integer, Float, Symbol] :const
+          #
+          #   @option spec [Proc] :enum
+          #
+          #   @option spec [Proc] :union
+          #
+          #   @option spec [Boolean] :"nil?"
+          #
+          # @return [Proc]
+          def type_info(spec)
+            case spec
+            in Proc
+              spec
+            in Hash
+              type_info(spec.slice(:const, :enum, :union).first&.last)
+            in true | false
+              -> { Lithic::Internal::Type::Boolean }
+            in Lithic::Internal::Type::Converter | Class | Symbol
+              -> { spec }
+            in NilClass | Integer | Float
+              -> { spec.class }
+            end
+          end
+
+          # @api private
+          #
+          # Based on `target`, transform `value` into `target`, to the extent possible:
+          #
+          #   1. if the given `value` conforms to `target` already, return the given `value`
+          #   2. if it's possible and safe to convert the given `value` to `target`, then the
+          #      converted value
+          #   3. otherwise, the given `value` unaltered
+          #
+          #   The coercion process is subject to improvement between minor release versions.
+          #   See https://docs.pydantic.dev/latest/concepts/unions/#smart-mode
+          #
+          # @param target [Lithic::Internal::Type::Converter, Class]
+          #
+          # @param value [Object]
+          #
+          # @param state [Hash{Symbol=>Object}] The `strictness` is one of `true`, `false`, or `:strong`. This informs the
+          #   coercion strategy when we have to decide between multiple possible conversion
+          #   targets:
+          #
+          #   - `true`: the conversion must be exact, with minimum coercion.
+          #   - `false`: the conversion can be approximate, with some coercion.
+          #   - `:strong`: the conversion must be exact, with no coercion, and raise an error
+          #     if not possible.
+          #
+          #   The `exactness` is `Hash` with keys being one of `yes`, `no`, or `maybe`. For
+          #   any given conversion attempt, the exactness will be updated based on how closely
+          #   the value recursively matches the target type:
+          #
+          #   - `yes`: the value can be converted to the target type with minimum coercion.
+          #   - `maybe`: the value can be converted to the target type with some reasonable
+          #     coercion.
+          #   - `no`: the value cannot be converted to the target type.
+          #
+          #   See implementation below for more details.
+          #
+          #   @option state [Boolean, :strong] :strictness
+          #
+          #   @option state [Hash{Symbol=>Object}] :exactness
+          #
+          #   @option state [Integer] :branched
+          #
+          # @return [Object]
+          def coerce(
+            target,
+            value,
+            state: {strictness: true, exactness: {yes: 0, no: 0, maybe: 0}, branched: 0}
+          )
+            # rubocop:disable Lint/SuppressedException
+            # rubocop:disable Metrics/BlockNesting
+            strictness, exactness = state.fetch_values(:strictness, :exactness)
+
+            case target
+            in Lithic::Internal::Type::Converter
+              return target.coerce(value, state: state)
+            in Class
+              if value.is_a?(target)
+                exactness[:yes] += 1
+                return value
+              end
+
+              case target
+              in -> { _1 <= NilClass }
+                exactness[value.nil? ? :yes : :maybe] += 1
+                return nil
+              in -> { _1 <= Integer }
+                if value.is_a?(Integer)
+                  exactness[:yes] += 1
+                  return value
+                elsif strictness == :strong
+                  message = "no implicit conversion of #{value.class} into #{target.inspect}"
+                  raise TypeError.new(message)
+                else
+                  Kernel.then do
+                    return Integer(value).tap { exactness[:maybe] += 1 }
+                  rescue ArgumentError, TypeError
+                  end
+                end
+              in -> { _1 <= Float }
+                if value.is_a?(Numeric)
+                  exactness[:yes] += 1
+                  return Float(value)
+                elsif strictness == :strong
+                  message = "no implicit conversion of #{value.class} into #{target.inspect}"
+                  raise TypeError.new(message)
+                else
+                  Kernel.then do
+                    return Float(value).tap { exactness[:maybe] += 1 }
+                  rescue ArgumentError, TypeError
+                  end
+                end
+              in -> { _1 <= String }
+                case value
+                in String | Symbol | Numeric
+                  exactness[value.is_a?(Numeric) ? :maybe : :yes] += 1
+                  return value.to_s
+                in StringIO
+                  exactness[:yes] += 1
+                  return value.string
+                else
+                  if strictness == :strong
+                    message = "no implicit conversion of #{value.class} into #{target.inspect}"
+                    raise TypeError.new(message)
+                  end
+                end
+              in -> { _1 <= Date || _1 <= Time }
+                Kernel.then do
+                  return target.parse(value).tap { exactness[:yes] += 1 }
+                rescue ArgumentError, TypeError => e
+                  raise e if strictness == :strong
+                end
+              in -> { _1 <= IO } if value.is_a?(String)
+                exactness[:yes] += 1
+                return StringIO.new(value.b)
+              else
+              end
+            in Symbol
+              if (value.is_a?(Symbol) || value.is_a?(String)) && value.to_sym == target
+                exactness[:yes] += 1
+                return target
+              elsif strictness == :strong
+                message = "cannot convert non-matching #{value.class} into #{target.inspect}"
+                raise ArgumentError.new(message)
+              end
+            else
+            end
+
+            exactness[:no] += 1
+            value
+            # rubocop:enable Metrics/BlockNesting
+            # rubocop:enable Lint/SuppressedException
+          end
+
+          # @api private
+          #
+          # @param target [Lithic::Internal::Type::Converter, Class]
+          # @param value [Object]
+          #
+          # @return [Object]
+          def dump(target, value)
+            # rubocop:disable Layout/LineLength
+            target.is_a?(Lithic::Internal::Type::Converter) ? target.dump(value) : Lithic::Internal::Type::Unknown.dump(value)
+            # rubocop:enable Layout/LineLength
+          end
+        end
+      end
+      # rubocop:enable Metrics/ModuleLength
+    end
+  end
+end

data/lib/lithic/internal/type/enum.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Lithic
+  module Internal
+    module Type
+      # @api private
+      #
+      # A value from among a specified list of options. OpenAPI enum values map to Ruby
+      #   values in the SDK as follows:
+      #
+      #   1. boolean => true | false
+      #   2. integer => Integer
+      #   3. float => Float
+      #   4. string => Symbol
+      #
+      #   We can therefore convert string values to Symbols, but can't convert other
+      #   values safely.
+      #
+      # @example
+      #   # `account_financial_account_type` is a `Lithic::Models::AccountFinancialAccountType`
+      #   case account_financial_account_type
+      #   when Lithic::Models::AccountFinancialAccountType::ISSUING
+      #     # ...
+      #   when Lithic::Models::AccountFinancialAccountType::OPERATING
+      #     # ...
+      #   else
+      #     puts(account_financial_account_type)
+      #   end
+      #
+      # @example
+      #   case account_financial_account_type
+      #   in :ISSUING
+      #     # ...
+      #   in :OPERATING
+      #     # ...
+      #   else
+      #     puts(account_financial_account_type)
+      #   end
+      module Enum
+        include Lithic::Internal::Type::Converter
+
+        # All of the valid Symbol values for this enum.
+        #
+        # @return [Array<NilClass, Boolean, Integer, Float, Symbol>]
+        def values = (@values ||= constants.map { const_get(_1) })
+
+        # @api private
+        #
+        # Guard against thread safety issues by instantiating `@values`.
+        private def finalize! = values
+
+        # @param other [Object]
+        #
+        # @return [Boolean]
+        def ===(other) = values.include?(other)
+
+        # @param other [Object]
+        #
+        # @return [Boolean]
+        def ==(other)
+          # rubocop:disable Layout/LineLength
+          other.is_a?(Module) && other.singleton_class <= Lithic::Internal::Type::Enum && other.values.to_set == values.to_set
+          # rubocop:enable Layout/LineLength
+        end
+
+        # @api private
+        #
+        # Unlike with primitives, `Enum` additionally validates that the value is a member
+        #   of the enum.
+        #
+        # @param value [String, Symbol, Object]
+        #
+        # @param state [Hash{Symbol=>Object}] .
+        #
+        #   @option state [Boolean, :strong] :strictness
+        #
+        #   @option state [Hash{Symbol=>Object}] :exactness
+        #
+        #   @option state [Integer] :branched
+        #
+        # @return [Symbol, Object]
+        def coerce(value, state:)
+          exactness = state.fetch(:exactness)
+          val = value.is_a?(String) ? value.to_sym : value
+
+          if values.include?(val)
+            exactness[:yes] += 1
+            val
+          else
+            exactness[values.first&.class == val.class ? :maybe : :no] += 1
+            value
+          end
+        end
+
+        # @!parse
+        #   # @api private
+        #   #
+        #   # @param value [Symbol, Object]
+        #   #
+        #   # @return [Symbol, Object]
+        #   def dump(value) = super
+      end
+    end
+  end
+end

data/lib/lithic/internal/type/hash_of.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module Lithic
+  module Internal
+    module Type
+      # @api private
+      #
+      # @abstract
+      #
+      # @generic Elem
+      #
+      # Hash of items of a given type.
+      class HashOf
+        include Lithic::Internal::Type::Converter
+
+        # @param type_info [Hash{Symbol=>Object}, Proc, Lithic::Internal::Type::Converter, Class]
+        #
+        # @param spec [Hash{Symbol=>Object}] .
+        #
+        #   @option spec [NilClass, TrueClass, FalseClass, Integer, Float, Symbol] :const
+        #
+        #   @option spec [Proc] :enum
+        #
+        #   @option spec [Proc] :union
+        #
+        #   @option spec [Boolean] :"nil?"
+        def self.[](type_info, spec = {}) = new(type_info, spec)
+
+        # @param other [Object]
+        #
+        # @return [Boolean]
+        def ===(other)
+          type = item_type
+          case other
+          in Hash
+            other.all? do |key, val|
+              case [key, val]
+              in [Symbol | String, ^type]
+                true
+              else
+                false
+              end
+            end
+          else
+            false
+          end
+        end
+
+        # @param other [Object]
+        #
+        # @return [Boolean]
+        def ==(other)
+          # rubocop:disable Layout/LineLength
+          other.is_a?(Lithic::Internal::Type::HashOf) && other.nilable? == nilable? && other.item_type == item_type
+          # rubocop:enable Layout/LineLength
+        end
+
+        # @api private
+        #
+        # @param value [Hash{Object=>Object}, Object]
+        #
+        # @param state [Hash{Symbol=>Object}] .
+        #
+        #   @option state [Boolean, :strong] :strictness
+        #
+        #   @option state [Hash{Symbol=>Object}] :exactness
+        #
+        #   @option state [Integer] :branched
+        #
+        # @return [Hash{Symbol=>Object}, Object]
+        def coerce(value, state:)
+          exactness = state.fetch(:exactness)
+
+          unless value.is_a?(Hash)
+            exactness[:no] += 1
+            return value
+          end
+
+          target = item_type
+          exactness[:yes] += 1
+          value
+            .to_h do |key, val|
+              k = key.is_a?(String) ? key.to_sym : key
+              v =
+                case [nilable?, val]
+                in [true, nil]
+                  exactness[:yes] += 1
+                  nil
+                else
+                  Lithic::Internal::Type::Converter.coerce(target, val, state: state)
+                end
+
+              exactness[:no] += 1 unless k.is_a?(Symbol)
+              [k, v]
+            end
+        end
+
+        # @api private
+        #
+        # @param value [Hash{Object=>Object}, Object]
+        #
+        # @return [Hash{Symbol=>Object}, Object]
+        def dump(value)
+          target = item_type
+          if value.is_a?(Hash)
+            value.transform_values do
+              Lithic::Internal::Type::Converter.dump(target, _1)
+            end
+          else
+            super
+          end
+        end
+
+        # @api private
+        #
+        # @return [generic<Elem>]
+        protected def item_type = @item_type_fn.call
+
+        # @api private
+        #
+        # @return [Boolean]
+        protected def nilable? = @nilable
+
+        # @api private
+        #
+        # @param type_info [Hash{Symbol=>Object}, Proc, Lithic::Internal::Type::Converter, Class]
+        #
+        # @param spec [Hash{Symbol=>Object}] .
+        #
+        #   @option spec [NilClass, TrueClass, FalseClass, Integer, Float, Symbol] :const
+        #
+        #   @option spec [Proc] :enum
+        #
+        #   @option spec [Proc] :union
+        #
+        #   @option spec [Boolean] :"nil?"
+        def initialize(type_info, spec = {})
+          @item_type_fn = Lithic::Internal::Type::Converter.type_info(type_info || spec)
+          @nilable = spec[:nil?]
+        end
+      end
+    end
+  end
+end

data/lib/lithic/internal/type/request_parameters.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Lithic
+  module Internal
+    module Type
+      # @api private
+      module RequestParameters
+        # @!parse
+        #   # Options to specify HTTP behaviour for this request.
+        #   # @return [Lithic::RequestOptions, Hash{Symbol=>Object}]
+        #   attr_accessor :request_options
+
+        # @param mod [Module]
+        def self.included(mod)
+          return unless mod <= Lithic::Internal::Type::BaseModel
+
+          mod.extend(Lithic::Internal::Type::RequestParameters::Converter)
+          mod.optional(:request_options, Lithic::RequestOptions)
+        end
+
+        # @api private
+        module Converter
+          # @api private
+          #
+          # @param params [Object]
+          #
+          # @return [Array(Object, Hash{Symbol=>Object})]
+          def dump_request(params)
+            case (dumped = dump(params))
+            in Hash
+              [dumped.except(:request_options), dumped[:request_options]]
+            else
+              [dumped, nil]
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lithic/internal/type/union.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+module Lithic
+  module Internal
+    module Type
+      # @api private
+      #
+      # @example
+      #   # `account_holder_update_response` is a `Lithic::Models::AccountHolderUpdateResponse`
+      #   case account_holder_update_response
+      #   when Lithic::Models::AccountHolderUpdateResponse::KYBKYCPatchResponse
+      #     puts(account_holder_update_response.token)
+      #   when Lithic::Models::AccountHolderUpdateResponse::PatchResponse
+      #     puts(account_holder_update_response.address)
+      #   else
+      #     puts(account_holder_update_response)
+      #   end
+      module Union
+        include Lithic::Internal::Type::Converter
+
+        # @api private
+        #
+        # All of the specified variant info for this union.
+        #
+        # @return [Array<Array(Symbol, Proc)>]
+        private def known_variants = (@known_variants ||= [])
+
+        # @api private
+        #
+        # @return [Array<Array(Symbol, Object)>]
+        protected def derefed_variants
+          @known_variants.map { |key, variant_fn| [key, variant_fn.call] }
+        end
+
+        # All of the specified variants for this union.
+        #
+        # @return [Array<Object>]
+        def variants = derefed_variants.map(&:last)
+
+        # @api private
+        #
+        # @param property [Symbol]
+        private def discriminator(property)
+          case property
+          in Symbol
+            @discriminator = property
+          end
+        end
+
+        # @api private
+        #
+        # @param key [Symbol, Hash{Symbol=>Object}, Proc, Lithic::Internal::Type::Converter, Class]
+        #
+        # @param spec [Hash{Symbol=>Object}, Proc, Lithic::Internal::Type::Converter, Class] .
+        #
+        #   @option spec [NilClass, TrueClass, FalseClass, Integer, Float, Symbol] :const
+        #
+        #   @option spec [Proc] :enum
+        #
+        #   @option spec [Proc] :union
+        #
+        #   @option spec [Boolean] :"nil?"
+        private def variant(key, spec = nil)
+          variant_info =
+            case key
+            in Symbol
+              [key, Lithic::Internal::Type::Converter.type_info(spec)]
+            in Proc | Lithic::Internal::Type::Converter | Class | Hash
+              [nil, Lithic::Internal::Type::Converter.type_info(key)]
+            end
+
+          known_variants << variant_info
+        end
+
+        # @api private
+        #
+        # @param value [Object]
+        #
+        # @return [Lithic::Internal::Type::Converter, Class, nil]
+        private def resolve_variant(value)
+          case [@discriminator, value]
+          in [_, Lithic::Internal::Type::BaseModel]
+            value.class
+          in [Symbol, Hash]
+            key = value.fetch(@discriminator) do
+              value.fetch(@discriminator.to_s, Lithic::Internal::OMIT)
+            end
+
+            return nil if key == Lithic::Internal::OMIT
+
+            key = key.to_sym if key.is_a?(String)
+            known_variants.find { |k,| k == key }&.last&.call
+          else
+            nil
+          end
+        end
+
+        # rubocop:disable Style/HashEachMethods
+        # rubocop:disable Style/CaseEquality
+
+        # @param other [Object]
+        #
+        # @return [Boolean]
+        def ===(other)
+          known_variants.any? do |_, variant_fn|
+            variant_fn.call === other
+          end
+        end
+
+        # @param other [Object]
+        #
+        # @return [Boolean]
+        def ==(other)
+          # rubocop:disable Layout/LineLength
+          other.is_a?(Module) && other.singleton_class <= Lithic::Internal::Type::Union && other.derefed_variants == derefed_variants
+          # rubocop:enable Layout/LineLength
+        end
+
+        # @api private
+        #
+        # @param value [Object]
+        #
+        # @param state [Hash{Symbol=>Object}] .
+        #
+        #   @option state [Boolean, :strong] :strictness
+        #
+        #   @option state [Hash{Symbol=>Object}] :exactness
+        #
+        #   @option state [Integer] :branched
+        #
+        # @return [Object]
+        def coerce(value, state:)
+          if (target = resolve_variant(value))
+            return Lithic::Internal::Type::Converter.coerce(target, value, state: state)
+          end
+
+          strictness = state.fetch(:strictness)
+          exactness = state.fetch(:exactness)
+          state[:strictness] = strictness == :strong ? true : strictness
+
+          alternatives = []
+          known_variants.each do |_, variant_fn|
+            target = variant_fn.call
+            exact = state[:exactness] = {yes: 0, no: 0, maybe: 0}
+            state[:branched] += 1
+
+            coerced = Lithic::Internal::Type::Converter.coerce(target, value, state: state)
+            yes, no, maybe = exact.values
+            if (no + maybe).zero? || (!strictness && yes.positive?)
+              exact.each { exactness[_1] += _2 }
+              state[:exactness] = exactness
+              return coerced
+            elsif maybe.positive?
+              alternatives << [[-yes, -maybe, no], exact, coerced]
+            end
+          end
+
+          case alternatives.sort_by(&:first)
+          in []
+            exactness[:no] += 1
+            if strictness == :strong
+              message = "no possible conversion of #{value.class} into a variant of #{target.inspect}"
+              raise ArgumentError.new(message)
+            end
+            value
+          in [[_, exact, coerced], *]
+            exact.each { exactness[_1] += _2 }
+            coerced
+          end
+            .tap { state[:exactness] = exactness }
+        ensure
+          state[:strictness] = strictness
+        end
+
+        # @api private
+        #
+        # @param value [Object]
+        #
+        # @return [Object]
+        def dump(value)
+          if (target = resolve_variant(value))
+            return Lithic::Internal::Type::Converter.dump(target, value)
+          end
+
+          known_variants.each do
+            target = _2.call
+            return Lithic::Internal::Type::Converter.dump(target, value) if target === value
+          end
+
+          super
+        end
+
+        # rubocop:enable Style/CaseEquality
+        # rubocop:enable Style/HashEachMethods
+      end
+    end
+  end
+end