finch-api 0.1.0.pre.alpha.4 → 0.1.0.pre.alpha.5

data/lib/finch-api/type/converter.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  module Type
+    # @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 { FinchAPI::Unknown.dump(_1) }
+        in Hash
+          value.transform_values { FinchAPI::Unknown.dump(_1) }
+        in FinchAPI::BaseModel
+          value.class.dump(value)
+        else
+          value
+        end
+      end
+
+      # rubocop:enable Lint/UnusedMethodArgument
+
+      class << self
+        # @api private
+        #
+        # @param spec [Hash{Symbol=>Object}, Proc, FinchAPI::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
+            -> { FinchAPI::BooleanModel }
+          in FinchAPI::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 [FinchAPI::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}
+        )
+          strictness, exactness = state.fetch_values(:strictness, :exactness)
+
+          case target
+          in FinchAPI::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
+              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
+        end
+
+        # @api private
+        #
+        # @param target [FinchAPI::Type::Converter, Class]
+        # @param value [Object]
+        #
+        # @return [Object]
+        def dump(target, value)
+          target.is_a?(FinchAPI::Type::Converter) ? target.dump(value) : FinchAPI::Unknown.dump(value)
+        end
+      end
+    end
+  end
+end

data/lib/finch-api/type/enum.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  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
+    #   # `connection_status_type` is a `FinchAPI::Models::ConnectionStatusType`
+    #   case connection_status_type
+    #   when FinchAPI::Models::ConnectionStatusType::PENDING
+    #     # ...
+    #   when FinchAPI::Models::ConnectionStatusType::PROCESSING
+    #     # ...
+    #   when FinchAPI::Models::ConnectionStatusType::CONNECTED
+    #     # ...
+    #   else
+    #     puts(connection_status_type)
+    #   end
+    #
+    # @example
+    #   case connection_status_type
+    #   in :pending
+    #     # ...
+    #   in :processing
+    #     # ...
+    #   in :connected
+    #     # ...
+    #   else
+    #     puts(connection_status_type)
+    #   end
+    module Enum
+      include FinchAPI::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)
+        other.is_a?(Module) && other.singleton_class <= FinchAPI::Enum && other.values.to_set == values.to_set
+      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

data/lib/finch-api/type/hash_of.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  module Type
+    # @api private
+    #
+    # @abstract
+    #
+    # Hash of items of a given type.
+    class HashOf
+      include FinchAPI::Type::Converter
+
+      # @param type_info [Hash{Symbol=>Object}, Proc, FinchAPI::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) = other.is_a?(FinchAPI::HashOf) && other.nilable? == nilable? && other.item_type == item_type
+
+      # @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
+                FinchAPI::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
+            FinchAPI::Type::Converter.dump(target, _1)
+          end
+        else
+          super
+        end
+      end
+
+      # @api private
+      #
+      # @return [FinchAPI::Type::Converter, Class]
+      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, FinchAPI::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 = FinchAPI::Type::Converter.type_info(type_info || spec)
+        @nilable = spec[:nil?]
+      end
+    end
+  end
+end

data/lib/finch-api/type/request_parameters.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  module Type
+    # @api private
+    module RequestParameters
+      # @!parse
+      #   # Options to specify HTTP behaviour for this request.
+      #   # @return [FinchAPI::RequestOptions, Hash{Symbol=>Object}]
+      #   attr_accessor :request_options
+
+      # @param mod [Module]
+      def self.included(mod)
+        return unless mod <= FinchAPI::BaseModel
+
+        mod.extend(FinchAPI::Type::RequestParameters::Converter)
+        mod.optional(:request_options, FinchAPI::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

data/lib/finch-api/type/union.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  module Type
+    # @api private
+    #
+    # @example
+    #   # `document_retreive_response` is a `FinchAPI::Models::HRIS::DocumentRetreiveResponse`
+    #   case document_retreive_response
+    #   when FinchAPI::Models::HRIS::W42020
+    #     puts(document_retreive_response.data)
+    #   when FinchAPI::Models::HRIS::W42005
+    #     puts(document_retreive_response.type)
+    #   else
+    #     puts(document_retreive_response)
+    #   end
+    #
+    # @example
+    #   case document_retreive_response
+    #   in {type: :w4_2020, data: data, year: year}
+    #     puts(data)
+    #   in {type: :w4_2005, data: data, year: year}
+    #     puts(year)
+    #   else
+    #     puts(document_retreive_response)
+    #   end
+    module Union
+      include FinchAPI::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, FinchAPI::Type::Converter, Class]
+      #
+      # @param spec [Hash{Symbol=>Object}, Proc, FinchAPI::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, FinchAPI::Type::Converter.type_info(spec)]
+          in Proc | FinchAPI::Type::Converter | Class | Hash
+            [nil, FinchAPI::Type::Converter.type_info(key)]
+          end
+
+        known_variants << variant_info
+      end
+
+      # @api private
+      #
+      # @param value [Object]
+      #
+      # @return [FinchAPI::Type::Converter, Class, nil]
+      private def resolve_variant(value)
+        case [@discriminator, value]
+        in [_, FinchAPI::BaseModel]
+          value.class
+        in [Symbol, Hash]
+          key = value.fetch(@discriminator) do
+            value.fetch(@discriminator.to_s, FinchAPI::Util::OMIT)
+          end
+
+          return nil if key == FinchAPI::Util::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)
+        other.is_a?(Module) && other.singleton_class <= FinchAPI::Union && other.derefed_variants == derefed_variants
+      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 FinchAPI::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 = FinchAPI::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 FinchAPI::Type::Converter.dump(target, value)
+        end
+
+        known_variants.each do
+          target = _2.call
+          return FinchAPI::Type::Converter.dump(target, value) if target === value
+        end
+
+        super
+      end
+
+      # rubocop:enable Style/CaseEquality
+      # rubocop:enable Style/HashEachMethods
+    end
+  end
+end