modern_treasury 0.1.0.pre.alpha.17 → 0.1.0.pre.alpha.19

data/lib/modern_treasury/internal/type/base_model.rb

@@ -4,15 +4,9 @@ module ModernTreasury
   module Internal
     module Type
       # @abstract
-      #
-      # @example
-      #   # `async_response` is a `ModernTreasury::Models::AsyncResponse`
-      #   async_response => {
-      #     id: id,
-      #     object: object
-      #   }
       class BaseModel
         extend ModernTreasury::Internal::Type::Converter
+        extend ModernTreasury::Internal::Util::SorbetRuntimeSupport
 
         class << self
           # @api private
@@ -20,11 +14,17 @@ module ModernTreasury
           # Assumes superclass fields are totally defined before fields are accessed /
           # defined on subclasses.
           #
-          # @return [Hash{Symbol=>Hash{Symbol=>Object}}]
-          def known_fields
-            @known_fields ||= (self < ModernTreasury::Internal::Type::BaseModel ? superclass.known_fields.dup : {})
+          # @param child [Class<ModernTreasury::Internal::Type::BaseModel>]
+          def inherited(child)
+            super
+            child.known_fields.replace(known_fields.dup)
           end
 
+          # @api private
+          #
+          # @return [Hash{Symbol=>Hash{Symbol=>Object}}]
+          def known_fields = @known_fields ||= {}
+
           # @api private
           #
           # @return [Hash{Symbol=>Hash{Symbol=>Object}}]
@@ -62,7 +62,7 @@ module ModernTreasury
 
             setter = "#{name_sym}="
             api_name = info.fetch(:api_name, name_sym)
-            nilable = info[:nil?]
+            nilable = info.fetch(:nil?, false)
             const = if required && !nilable
               info.fetch(
                 :const,
@@ -97,11 +97,13 @@ module ModernTreasury
                   target, value, state: state
                 )
               end
-            rescue StandardError
+            rescue StandardError => e
               cls = self.class.name.split("::").last
-              # rubocop:disable Layout/LineLength
-              message = "Failed to parse #{cls}.#{__method__} from #{value.class} to #{target.inspect}. To get the unparsed API response, use #{cls}[:#{__method__}]."
-              # rubocop:enable Layout/LineLength
+              message = [
+                "Failed to parse #{cls}.#{__method__} from #{value.class} to #{target.inspect}.",
+                "To get the unparsed API response, use #{cls}[#{__method__.inspect}].",
+                "Cause: #{e.message}"
+              ].join(" ")
               raise ModernTreasury::Errors::ConversionError.new(message)
             end
           end
@@ -169,19 +171,33 @@ module ModernTreasury
             @mode = nil
           end
 
+          # @api public
+          #
           # @param other [Object]
           #
           # @return [Boolean]
           def ==(other)
             other.is_a?(Class) && other <= ModernTreasury::Internal::Type::BaseModel && other.fields == fields
           end
+
+          # @api public
+          #
+          # @return [Integer]
+          def hash = fields.hash
         end
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
         def ==(other) = self.class == other.class && @data == other.to_h
 
+        # @api public
+        #
+        # @return [Integer]
+        def hash = [self.class, @data].hash
+
         class << self
           # @api private
           #
@@ -195,7 +211,7 @@ module ModernTreasury
           #
           #   @option state [Integer] :branched
           #
-          # @return [ModernTreasury::Internal::Type::BaseModel, Object]
+          # @return [self, Object]
           def coerce(value, state:)
             exactness = state.fetch(:exactness)
 
@@ -254,10 +270,14 @@ module ModernTreasury
 
           # @api private
           #
-          # @param value [ModernTreasury::Internal::Type::BaseModel, Object]
+          # @param value [self, Object]
+          #
+          # @param state [Hash{Symbol=>Object}] .
+          #
+          #   @option state [Boolean] :can_retry
           #
           # @return [Hash{Object=>Object}, Object]
-          def dump(value)
+          def dump(value, state:)
             unless (coerced = ModernTreasury::Internal::Util.coerce_hash(value)).is_a?(Hash)
               return super
             end
@@ -268,7 +288,7 @@ module ModernTreasury
               name = key.is_a?(String) ? key.to_sym : key
               case (field = known_fields[name])
               in nil
-                acc.store(name, super(val))
+                acc.store(name, super(val, state: state))
               else
                 api_name, mode, type_fn = field.fetch_values(:api_name, :mode, :type_fn)
                 case mode
@@ -276,7 +296,10 @@ module ModernTreasury
                   next
                 else
                   target = type_fn.call
-                  acc.store(api_name, ModernTreasury::Internal::Type::Converter.dump(target, val))
+                  acc.store(
+                    api_name,
+                    ModernTreasury::Internal::Type::Converter.dump(target, val, state: state)
+                  )
                 end
               end
             end
@@ -291,6 +314,41 @@ module ModernTreasury
           end
         end
 
+        class << self
+          # @api private
+          #
+          # @param model [ModernTreasury::Internal::Type::BaseModel]
+          # @param convert [Boolean]
+          #
+          # @return [Hash{Symbol=>Object}]
+          def recursively_to_h(model, convert:)
+            rec = ->(x) do
+              case x
+              in ModernTreasury::Internal::Type::BaseModel
+                if convert
+                  fields = x.class.known_fields
+                  x.to_h.to_h do |key, val|
+                    [key, rec.call(fields.key?(key) ? x.public_send(key) : val)]
+                  rescue ModernTreasury::Errors::ConversionError
+                    [key, rec.call(val)]
+                  end
+                else
+                  rec.call(x.to_h)
+                end
+              in Hash
+                x.transform_values(&rec)
+              in Array
+                x.map(&rec)
+              else
+                x
+              end
+            end
+            rec.call(model)
+          end
+        end
+
+        # @api public
+        #
         # Returns the raw value associated with the given key, if found. Otherwise, nil is
         # returned.
         #
@@ -309,6 +367,8 @@ module ModernTreasury
           @data[key]
         end
 
+        # @api public
+        #
         # Returns a Hash of the data underlying this object. O(1)
         #
         # Keys are Symbols and values are the raw values from the response. The return
@@ -323,6 +383,14 @@ module ModernTreasury
 
         alias_method :to_hash, :to_h
 
+        # @api public
+        #
+        # In addition to the behaviour of `#to_h`, this method will recursively call
+        # `#to_h` on nested models.
+        #
+        # @return [Hash{Symbol=>Object}]
+        def deep_to_h = self.class.recursively_to_h(@data, convert: false)
+
         # @param keys [Array<Symbol>, nil]
         #
         # @return [Hash{Symbol=>Object}]
@@ -338,37 +406,63 @@ module ModernTreasury
             .to_h
         end
 
+        # @api public
+        #
         # @param a [Object]
         #
         # @return [String]
-        def to_json(*a) = self.class.dump(self).to_json(*a)
+        def to_json(*a) = ModernTreasury::Internal::Type::Converter.dump(self.class, self).to_json(*a)
 
+        # @api public
+        #
         # @param a [Object]
         #
         # @return [String]
-        def to_yaml(*a) = self.class.dump(self).to_yaml(*a)
+        def to_yaml(*a) = ModernTreasury::Internal::Type::Converter.dump(self.class, self).to_yaml(*a)
 
         # Create a new instance of a model.
         #
-        # @param data [Hash{Symbol=>Object}, ModernTreasury::Internal::Type::BaseModel]
-        def initialize(data = {})
-          case ModernTreasury::Internal::Util.coerce_hash(data)
-          in Hash => coerced
-            @data = coerced
-          else
-            message = "Expected a #{Hash} or #{ModernTreasury::Internal::Type::BaseModel}, got #{data.inspect}"
-            raise ArgumentError.new(message)
+        # @param data [Hash{Symbol=>Object}, self]
+        def initialize(data = {}) = (@data = ModernTreasury::Internal::Util.coerce_hash!(data).to_h)
+
+        class << self
+          # @api private
+          #
+          # @param depth [Integer]
+          #
+          # @return [String]
+          def inspect(depth: 0)
+            return super() if depth.positive?
+
+            depth = depth.succ
+            deferred = fields.transform_values do |field|
+              type, required, nilable = field.fetch_values(:type, :required, :nilable)
+              inspected = [
+                ModernTreasury::Internal::Type::Converter.inspect(type, depth: depth),
+                !required || nilable ? "nil" : nil
+              ].compact.join(" | ")
+              -> { inspected }.tap { _1.define_singleton_method(:inspect) { call } }
+            end
+
+            "#{name}[#{deferred.inspect}]"
           end
         end
 
+        # @api public
+        #
+        # @return [String]
+        def to_s = deep_to_h.to_s
+
+        # @api private
+        #
         # @return [String]
         def inspect
-          rows = self.class.known_fields.keys.map do
-            "#{_1}=#{@data.key?(_1) ? public_send(_1) : ''}"
-          rescue ModernTreasury::Errors::ConversionError
-            "#{_1}=#{@data.fetch(_1)}"
-          end
-          "#<#{self.class.name}:0x#{object_id.to_s(16)} #{rows.join(' ')}>"
+          converted = self.class.recursively_to_h(self, convert: true)
+          "#<#{self.class}:0x#{object_id.to_s(16)} #{converted}>"
+        end
+
+        define_sorbet_constant!(:KnownField) do
+          T.type_alias { {mode: T.nilable(Symbol), required: T::Boolean, nilable: T::Boolean} }
         end
       end
     end

data/lib/modern_treasury/internal/type/base_page.rb

@@ -3,19 +3,27 @@
 module ModernTreasury
   module Internal
     module Type
+      # @api private
+      #
       # @generic Elem
       #
       # This module provides a base implementation for paginated responses in the SDK.
       module BasePage
         # rubocop:disable Lint/UnusedMethodArgument
 
+        # @api public
+        #
         # @return [Boolean]
         def next_page? = (raise NotImplementedError)
 
+        # @api public
+        #
         # @raise [ModernTreasury::Errors::APIError]
-        # @return [ModernTreasury::Internal::Type::BasePage]
+        # @return [self]
         def next_page = (raise NotImplementedError)
 
+        # @api public
+        #
         # @param blk [Proc]
         #
         # @yieldparam [generic<Elem>]
@@ -36,6 +44,7 @@ module ModernTreasury
         def initialize(client:, req:, headers:, page_data:)
           @client = client
           @req = req
+          @model = req.fetch(:model)
           super()
         end
 

data/lib/modern_treasury/internal/type/boolean.rb

@@ -11,11 +11,17 @@ module ModernTreasury
       class Boolean
         extend ModernTreasury::Internal::Type::Converter
 
+        private_class_method :new
+
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
         def self.===(other) = other == true || other == false
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
@@ -40,13 +46,16 @@ module ModernTreasury
             value
           end
 
-          # @!parse
-          #   # @api private
-          #   #
-          #   # @param value [Boolean, Object]
-          #   #
-          #   # @return [Boolean, Object]
-          #   def dump(value) = super
+          # @!method dump(value, state:)
+          #   @api private
+          #
+          #   @param value [Boolean, Object]
+          #
+          #   @param state [Hash{Symbol=>Object}] .
+          #
+          #     @option state [Boolean] :can_retry
+          #
+          #   @return [Boolean, Object]
         end
       end
     end

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

@@ -5,6 +5,8 @@ module ModernTreasury
     module Type
       # @api private
       module Converter
+        extend ModernTreasury::Internal::Util::SorbetRuntimeSupport
+
         # rubocop:disable Lint/UnusedMethodArgument
 
         # @api private
@@ -26,20 +28,41 @@ module ModernTreasury
         #
         # @param value [Object]
         #
+        # @param state [Hash{Symbol=>Object}] .
+        #
+        #   @option state [Boolean] :can_retry
+        #
         # @return [Object]
-        def dump(value)
+        def dump(value, state:)
           case value
           in Array
-            value.map { ModernTreasury::Internal::Type::Unknown.dump(_1) }
+            value.map { ModernTreasury::Internal::Type::Unknown.dump(_1, state: state) }
           in Hash
-            value.transform_values { ModernTreasury::Internal::Type::Unknown.dump(_1) }
+            value.transform_values { ModernTreasury::Internal::Type::Unknown.dump(_1, state: state) }
           in ModernTreasury::Internal::Type::BaseModel
-            value.class.dump(value)
+            value.class.dump(value, state: state)
+          in StringIO
+            value.string
+          in Pathname | IO
+            state[:can_retry] = false if value.is_a?(IO)
+            ModernTreasury::FilePart.new(value)
+          in ModernTreasury::FilePart
+            state[:can_retry] = false if value.content.is_a?(IO)
+            value
           else
             value
           end
         end
 
+        # @api private
+        #
+        # @param depth [Integer]
+        #
+        # @return [String]
+        def inspect(depth: 0)
+          super()
+        end
+
         # rubocop:enable Lint/UnusedMethodArgument
 
         class << self
@@ -140,9 +163,9 @@ module ModernTreasury
                 if value.is_a?(Integer)
                   exactness[:yes] += 1
                   return value
-                elsif strictness == :strong
+                elsif strictness == :strong && Integer(value, exception: false) != value
                   message = "no implicit conversion of #{value.class} into #{target.inspect}"
-                  raise TypeError.new(message)
+                  raise value.is_a?(Numeric) ? ArgumentError.new(message) : TypeError.new(message)
                 else
                   Kernel.then do
                     return Integer(value).tap { exactness[:maybe] += 1 }
@@ -182,18 +205,26 @@ module ModernTreasury
                 rescue ArgumentError, TypeError => e
                   raise e if strictness == :strong
                 end
-              in -> { _1 <= IO } if value.is_a?(String)
+              in -> { _1 <= StringIO } 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)
+              case value
+              in Symbol | String
+                if value.to_sym == target
+                  exactness[:yes] += 1
+                  return target
+                else
+                  exactness[:maybe] += 1
+                  return value
+                end
+              else
+                if strictness == :strong
+                  message = "cannot convert non-matching #{value.class} into #{target.inspect}"
+                  raise ArgumentError.new(message)
+                end
               end
             else
             end
@@ -207,15 +238,54 @@ module ModernTreasury
           # @api private
           #
           # @param target [ModernTreasury::Internal::Type::Converter, Class]
+          #
           # @param value [Object]
           #
+          # @param state [Hash{Symbol=>Object}] .
+          #
+          #   @option state [Boolean] :can_retry
+          #
           # @return [Object]
-          def dump(target, value)
-            # rubocop:disable Layout/LineLength
-            target.is_a?(ModernTreasury::Internal::Type::Converter) ? target.dump(value) : ModernTreasury::Internal::Type::Unknown.dump(value)
-            # rubocop:enable Layout/LineLength
+          def dump(target, value, state: {can_retry: true})
+            case target
+            in ModernTreasury::Internal::Type::Converter
+              target.dump(value, state: state)
+            else
+              ModernTreasury::Internal::Type::Unknown.dump(value, state: state)
+            end
+          end
+
+          # @api private
+          #
+          # @param target [Object]
+          # @param depth [Integer]
+          #
+          # @return [String]
+          def inspect(target, depth:)
+            case target
+            in ModernTreasury::Internal::Type::Converter
+              target.inspect(depth: depth.succ)
+            else
+              target.inspect
+            end
           end
         end
+
+        define_sorbet_constant!(:Input) do
+          T.type_alias { T.any(ModernTreasury::Internal::Type::Converter, T::Class[T.anything]) }
+        end
+        define_sorbet_constant!(:CoerceState) do
+          T.type_alias do
+            {
+              strictness: T.any(T::Boolean, Symbol),
+              exactness: {yes: Integer, no: Integer, maybe: Integer},
+              branched: Integer
+            }
+          end
+        end
+        define_sorbet_constant!(:DumpState) do
+          T.type_alias { {can_retry: T::Boolean} }
+        end
       end
     end
   end

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

@@ -17,11 +17,11 @@ module ModernTreasury
       # values safely.
       #
       # @example
-      #   # `accounts_type` is a `ModernTreasury::Models::AccountsType`
+      #   # `accounts_type` is a `ModernTreasury::AccountsType`
       #   case accounts_type
-      #   when ModernTreasury::Models::AccountsType::EXTERNAL_ACCOUNTS
+      #   when ModernTreasury::AccountsType::EXTERNAL_ACCOUNTS
       #     # ...
-      #   when ModernTreasury::Models::AccountsType::INTERNAL_ACCOUNTS
+      #   when ModernTreasury::AccountsType::INTERNAL_ACCOUNTS
       #     # ...
       #   else
       #     puts(accounts_type)
@@ -38,31 +38,36 @@ module ModernTreasury
       #   end
       module Enum
         include ModernTreasury::Internal::Type::Converter
+        include ModernTreasury::Internal::Util::SorbetRuntimeSupport
 
         # All of the valid Symbol values for this enum.
         #
         # @return [Array<NilClass, Boolean, Integer, Float, Symbol>]
-        def values = (@values ||= constants.map { const_get(_1) })
+        def values = constants.map { const_get(_1) }
 
-        # @api private
+        # @api public
         #
-        # Guard against thread safety issues by instantiating `@values`.
-        private def finalize! = values
-
         # @param other [Object]
         #
         # @return [Boolean]
         def ===(other) = values.include?(other)
 
+        # @api public
+        #
         # @param other [Object]
         #
         # @return [Boolean]
         def ==(other)
-          # rubocop:disable Layout/LineLength
-          other.is_a?(Module) && other.singleton_class <= ModernTreasury::Internal::Type::Enum && other.values.to_set == values.to_set
-          # rubocop:enable Layout/LineLength
+          # rubocop:disable Style/CaseEquality
+          ModernTreasury::Internal::Type::Enum === other && other.values.to_set == values.to_set
+          # rubocop:enable Style/CaseEquality
         end
 
+        # @api public
+        #
+        # @return [Integer]
+        def hash = values.to_set.hash
+
         # @api private
         #
         # Unlike with primitives, `Enum` additionally validates that the value is a member
@@ -92,13 +97,32 @@ module ModernTreasury
           end
         end
 
-        # @!parse
-        #   # @api private
-        #   #
-        #   # @param value [Symbol, Object]
-        #   #
-        #   # @return [Symbol, Object]
-        #   def dump(value) = super
+        # @!method dump(value, state:)
+        #   @api private
+        #
+        #   @param value [Symbol, Object]
+        #
+        #   @param state [Hash{Symbol=>Object}] .
+        #
+        #     @option state [Boolean] :can_retry
+        #
+        #   @return [Symbol, Object]
+
+        # @api private
+        #
+        # @param depth [Integer]
+        #
+        # @return [String]
+        def inspect(depth: 0)
+          if depth.positive?
+            return is_a?(Module) ? super() : self.class.name
+          end
+
+          members = values.map { ModernTreasury::Internal::Type::Converter.inspect(_1, depth: depth.succ) }
+          prefix = is_a?(Module) ? name : self.class.name
+
+          "#{prefix}[#{members.join(' | ')}]"
+        end
       end
     end
   end