feat: expose recursive #to_h conversion

Author: stainless-app[bot]

lib/finch_api/internal/type/base_model.rb

@@ -313,6 +313,39 @@ def dump(value, state:)
           end
         end
 
+        class << self
+          # @api private
+          #
+          # @param model [FinchAPI::Internal::Type::BaseModel]
+          # @param convert [Boolean]
+          #
+          # @return [Hash{Symbol=>Object}]
+          def recursively_to_h(model, convert:)
+            rec = ->(x) do
+              case x
+              in FinchAPI::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 FinchAPI::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
@@ -349,6 +382,14 @@ def to_h = @data
 
         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}]
@@ -364,29 +405,6 @@ def deconstruct_keys(keys)
             .to_h
         end
 
-        class << self
-          # @api private
-          #
-          # @param model [FinchAPI::Internal::Type::BaseModel]
-          #
-          # @return [Hash{Symbol=>Object}]
-          def walk(model)
-            walk = ->(x) do
-              case x
-              in FinchAPI::Internal::Type::BaseModel
-                walk.call(x.to_h)
-              in Hash
-                x.transform_values(&walk)
-              in Array
-                x.map(&walk)
-              else
-                x
-              end
-            end
-            walk.call(model)
-          end
-        end
-
         # @api public
         #
         # @param a [Object]
@@ -432,12 +450,15 @@ def inspect(depth: 0)
         # @api public
         #
         # @return [String]
-        def to_s = self.class.walk(@data).to_s
+        def to_s = deep_to_h.to_s
 
         # @api private
         #
         # @return [String]
-        def inspect = "#<#{self.class}:0x#{object_id.to_s(16)} #{self}>"
+        def inspect
+          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} }

rbi/finch_api/internal/type/base_model.rbi

@@ -199,6 +199,18 @@ module FinchAPI
           end
         end
 
+        class << self
+          # @api private
+          sig do
+            params(
+              model: FinchAPI::Internal::Type::BaseModel,
+              convert: T::Boolean
+            ).returns(FinchAPI::Internal::AnyHash)
+          end
+          def recursively_to_h(model, convert:)
+          end
+        end
+
         # Returns the raw value associated with the given key, if found. Otherwise, nil is
         # returned.
         #
@@ -233,6 +245,12 @@ module FinchAPI
         def to_hash
         end
 
+        # In addition to the behaviour of `#to_h`, this method will recursively call
+        # `#to_h` on nested models.
+        sig { overridable.returns(FinchAPI::Internal::AnyHash) }
+        def deep_to_h
+        end
+
         sig do
           params(keys: T.nilable(T::Array[Symbol])).returns(
             FinchAPI::Internal::AnyHash
@@ -241,17 +259,6 @@ module FinchAPI
         def deconstruct_keys(keys)
         end
 
-        class << self
-          # @api private
-          sig do
-            params(model: FinchAPI::Internal::Type::BaseModel).returns(
-              FinchAPI::Internal::AnyHash
-            )
-          end
-          def walk(model)
-          end
-        end
-
         sig { params(a: T.anything).returns(String) }
         def to_json(*a)
         end

sig/finch_api/internal/type/base_model.rbs

@@ -68,17 +68,20 @@ module FinchAPI
           state: FinchAPI::Internal::Type::Converter::dump_state
         ) -> (::Hash[top, top] | top)
 
+        def self.recursively_to_h: (
+          FinchAPI::Internal::Type::BaseModel model,
+          convert: bool
+        ) -> ::Hash[Symbol, top]
+
         def []: (Symbol key) -> top?
 
         def to_h: -> ::Hash[Symbol, top]
 
         alias to_hash to_h
 
-        def deconstruct_keys: (::Array[Symbol]? keys) -> ::Hash[Symbol, top]
+        def deep_to_h: -> ::Hash[Symbol, top]
 
-        def self.walk: (
-          FinchAPI::Internal::Type::BaseModel model
-        ) -> ::Hash[Symbol, top]
+        def deconstruct_keys: (::Array[Symbol]? keys) -> ::Hash[Symbol, top]
 
         def to_json: (*top a) -> String