lithic 0.1.0.pre.alpha.1 → 0.1.0.pre.alpha.3

data/lib/lithic/type/boolean_model.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Lithic
+  module Type
+    # @api private
+    #
+    # @abstract
+    #
+    # Ruby has no Boolean class; this is something for models to refer to.
+    class BooleanModel
+      extend Lithic::Type::Converter
+
+      # @param other [Object]
+      #
+      # @return [Boolean]
+      def self.===(other) = other == true || other == false
+
+      # @param other [Object]
+      #
+      # @return [Boolean]
+      def self.==(other) = other.is_a?(Class) && other <= Lithic::BooleanModel
+
+      class << self
+        # @api private
+        #
+        # @param value [Boolean, Object]
+        #
+        # @param state [Hash{Symbol=>Object}] .
+        #
+        #   @option state [Boolean, :strong] :strictness
+        #
+        #   @option state [Hash{Symbol=>Object}] :exactness
+        #
+        #   @option state [Integer] :branched
+        #
+        # @return [Boolean, Object]
+        def coerce(value, state:)
+          state.fetch(:exactness)[value == true || value == false ? :yes : :no] += 1
+          value
+        end
+
+        # @!parse
+        #   # @api private
+        #   #
+        #   # @param value [Boolean, Object]
+        #   #
+        #   # @return [Boolean, Object]
+        #   def dump(value) = super
+      end
+    end
+  end
+end

data/lib/lithic/type/converter.rb

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

data/lib/lithic/type/enum.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Lithic
+  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::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 <= Lithic::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/lithic/type/hash_of.rb

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

data/lib/lithic/type/request_parameters.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Lithic
+  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::BaseModel
+
+        mod.extend(Lithic::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