apimatic_core 0.3.8 → 0.3.17

data/lib/apimatic-core/pagination/strategies/offset_pagination.rb

@@ -0,0 +1,63 @@
+module CoreLibrary
+  # Implements offset-based pagination strategy for API responses.
+  #
+  # This class manages pagination by updating an offset parameter in the request builder,
+  # allowing sequential retrieval of paginated data. It extracts and updates the offset
+  # based on a configurable JSON pointer and applies a metadata wrapper to each page response.
+  class OffsetPagination < PaginationStrategy
+    # Initializes an OffsetPagination instance with the given input pointer and metadata wrapper.
+    #
+    # @param input [String] JSON pointer indicating the pagination parameter to update.
+    # @param metadata_wrapper [Proc] Callable for handling pagination metadata.
+    # @raise [ArgumentError] If input is nil.
+    def initialize(input, metadata_wrapper)
+      super(metadata_wrapper)
+
+      raise ArgumentError, 'Input pointer for offset based pagination cannot be nil' if input.nil?
+
+      @input = input
+      @offset = 0
+    end
+
+    # Determines whether the offset pagination strategy is applicable
+    # based on the given HTTP response.
+    #
+    # @param [HttpResponse, nil] _response The response from the previous API call.
+    # @return [Boolean] Always returns true, as this strategy does not depend on the response content.
+    def applicable?(_response)
+      true
+    end
+
+    # Updates the request builder to fetch the next page of results using offset-based pagination.
+    #
+    # If this is the first page, initializes the offset from the request builder.
+    # Otherwise, increments the offset by the previous page size and updates the pagination parameter.
+    #
+    # @param paginated_data [PaginatedData] Contains the last response, request builder, and page size.
+    # @return [Object] An updated request builder configured for the next page request.
+    def apply(paginated_data)
+      last_response = paginated_data.last_response
+      request_builder = paginated_data.request_builder
+
+      # If there is no response yet, this is the first page
+      if last_response.nil?
+        param_value = request_builder.get_parameter_value_by_json_pointer(@input)
+        @offset = param_value.nil? ? 0 : Integer(param_value)
+
+        return request_builder
+      end
+
+      @offset += paginated_data.page_size
+
+      request_builder.get_updated_request_by_json_pointer(@input, @offset)
+    end
+
+    # Applies the metadata wrapper to the given page response, passing the current offset.
+    #
+    # @param page_response [Object] The response object for the current page.
+    # @return [Object] The result of the metadata wrapper with the page response and offset.
+    def apply_metadata_wrapper(page_response)
+      @metadata_wrapper.call(page_response, @offset)
+    end
+  end
+end

data/lib/apimatic-core/pagination/strategies/page_pagination.rb

@@ -0,0 +1,60 @@
+module CoreLibrary
+  # Implements a page-based pagination strategy for API requests.
+  #
+  # This class manages pagination by updating the request builder with the appropriate page number,
+  # using a JSON pointer to identify the pagination parameter. It also applies a metadata wrapper
+  # to each paged response, including the current page number.
+  class PagePagination < PaginationStrategy
+    # Initializes a PagePagination instance with the given input pointer and metadata wrapper.
+    #
+    # @param input [String] JSON pointer indicating the pagination parameter in the request.
+    # @param metadata_wrapper [Proc] A callable for wrapping pagination metadata.
+    # @raise [ArgumentError] If input is nil.
+    def initialize(input, metadata_wrapper)
+      super(metadata_wrapper)
+
+      raise ArgumentError, 'Input pointer for page based pagination cannot be nil' if input.nil?
+
+      @input = input
+      @page_number = 1
+    end
+
+    # Determines whether the page pagination strategy is applicable
+    # based on the given HTTP response.
+    #
+    # @param [HttpResponse, nil] _response The response from the previous API call.
+    # @return [Boolean] Always returns true, as this strategy does not depend on the response content.
+    def applicable?(_response)
+      true
+    end
+
+    # Updates the request builder to fetch the next page of results based on the current paginated data.
+    #
+    # @param paginated_data [PaginatedData] An object containing the last response, request builder, and page size.
+    # @return [Object] The updated request builder configured for the next page request.
+    def apply(paginated_data)
+      last_response = paginated_data.last_response
+      request_builder = paginated_data.request_builder
+
+      # If there is no response yet, this is the first page
+      if last_response.nil?
+        param_value = request_builder.get_parameter_value_by_json_pointer(@input)
+        @page_number = param_value.nil? ? 1 : Integer(param_value)
+
+        return request_builder
+      end
+
+      @page_number += 1 if paginated_data.page_size.positive?
+
+      request_builder.get_updated_request_by_json_pointer(@input, @page_number)
+    end
+
+    # Applies the metadata wrapper to the paged response, including the current page number.
+    #
+    # @param paged_response [Object] The response object for the current page.
+    # @return [Object] The result of the metadata wrapper with the paged response and current page number.
+    def apply_metadata_wrapper(paged_response)
+      @metadata_wrapper.call(paged_response, @page_number)
+    end
+  end
+end

data/lib/apimatic-core/request_builder.rb

@@ -1,6 +1,13 @@
 module CoreLibrary
   # This class is the builder of the http request for an API call.
   class RequestBuilder
+    PATH_PARAM_POINTER = '$request.path'.freeze
+    QUERY_PARAM_POINTER = '$request.query'.freeze
+    HEADER_PARAM_POINTER = '$request.headers'.freeze
+    BODY_PARAM_POINTER = '$request.body'.freeze
+
+    attr_reader :template_params, :query_params, :header_params, :body_params, :form_params
+
     # Creates an instance of RequestBuilder.
     def initialize
       @server = nil
@@ -13,7 +20,7 @@ module CoreLibrary
       @additional_form_params = {}
       @additional_query_params = {}
       @multipart_params = {}
-      @body_param = nil
+      @body_params = nil
       @body_serializer = nil
       @auth = nil
       @array_serialization_format = ArraySerializationFormat::INDEXED
@@ -112,10 +119,10 @@ module CoreLibrary
     def body_param(body_param)
       body_param.validate
       if !body_param.get_key.nil?
-        @body_param = {} if @body_param.nil?
-        @body_param[body_param.get_key] = body_param.get_value
+        @body_params = {} if @body_params.nil?
+        @body_params[body_param.get_key] = body_param.get_value
       else
-        @body_param = body_param.get_value
+        @body_params = body_param.get_value
       end
       self
     end
@@ -222,7 +229,11 @@ module CoreLibrary
         _request_headers.merge!(@header_params)
       end
 
-      _request_headers
+      _serialized_headers = _request_headers.transform_values do |value|
+        value.nil? ? value : ApiHelper.json_serialize(value)
+      end
+
+      _serialized_headers
     end
 
     # Processes the body parameter of the request (including form param, json body or xml body).
@@ -231,7 +242,7 @@ module CoreLibrary
       _has_form_params = !@form_params.nil? && @form_params.any?
       _has_additional_form_params = !@additional_form_params.nil? && @additional_form_params.any?
       _has_multipart_param = !@multipart_params.nil? && @multipart_params.any?
-      _has_body_param = !@body_param.nil?
+      _has_body_param = !@body_params.nil?
       _has_body_serializer = !@body_serializer.nil?
       _has_xml_attributes = !@xml_attributes.nil?
 
@@ -283,15 +294,15 @@ module CoreLibrary
     # Resolves the body parameter to appropriate type.
     # @return [Hash] The resolved body parameter as per the type.
     def resolve_body_param
-      if !@body_param.nil? && @body_param.is_a?(FileWrapper)
-        @header_params['content-type'] = @body_param.content_type if !@body_param.file.nil? &&
-                                                                     !@body_param.content_type.nil?
-        @header_params['content-length'] = @body_param.file.size.to_s
-        return @body_param.file
-      elsif !@body_param.nil? && @body_param.is_a?(File)
-        @header_params['content-length'] = @body_param.size.to_s
+      if !@body_params.nil? && @body_params.is_a?(FileWrapper)
+        @header_params['content-type'] = @body_params.content_type if
+          !@body_params.file.nil? && !@body_params.content_type.nil?
+        @header_params['content-length'] = @body_params.file.size.to_s
+        return @body_params.file
+      elsif !@body_params.nil? && @body_params.is_a?(File)
+        @header_params['content-length'] = @body_params.size.to_s
       end
-      @body_param
+      @body_params
     end
 
     # Applies the configured auth onto the http request.
@@ -302,5 +313,119 @@ module CoreLibrary
       @auth.apply(http_request) if is_valid_auth
       raise AuthValidationException, @auth.error_message if !@auth.nil? && !is_valid_auth
     end
+
+    # Updates the given request builder by modifying its path, query,
+    # or header parameters based on the specified JSON pointer and value.
+    #
+    # @param json_pointer [String] JSON pointer indicating which parameter to update.
+    # @param value [Object] The value to set at the specified parameter location.
+    # @return [Object] The updated request builder with the modified parameter.
+    def get_updated_request_by_json_pointer(json_pointer, value)
+      param_pointer, field_pointer = JsonPointerHelper.split_into_parts(json_pointer)
+
+      template_params = nil
+      query_params = nil
+      header_params = nil
+      body_params = nil
+      form_params = nil
+
+      case param_pointer
+      when PATH_PARAM_POINTER
+        template_params = JsonPointerHelper.update_entry_by_json_pointer(
+          DeepCloneUtils.deep_copy(@template_params), "#{field_pointer}/value", value
+        )
+      when QUERY_PARAM_POINTER
+        query_params = JsonPointerHelper.update_entry_by_json_pointer(
+          DeepCloneUtils.deep_copy(@query_params), field_pointer, value
+        )
+      when HEADER_PARAM_POINTER
+        header_params = JsonPointerHelper.update_entry_by_json_pointer(
+          DeepCloneUtils.deep_copy(@header_params), field_pointer, value
+        )
+      when BODY_PARAM_POINTER
+        if @body_params
+          body_params = JsonPointerHelper.update_entry_by_json_pointer(
+            DeepCloneUtils.deep_copy(@body_params), field_pointer, value
+          )
+        else
+          form_params = JsonPointerHelper.update_entry_by_json_pointer(
+            DeepCloneUtils.deep_copy(@form_params), field_pointer, value
+          )
+        end
+      else
+        clone_with
+      end
+
+      clone_with(
+        template_params: template_params,
+        query_params: query_params,
+        header_params: header_params,
+        body_params: body_params,
+        form_params: form_params
+      )
+    end
+
+    # Extracts the initial pagination offset value from the request builder using the specified JSON pointer.
+    #
+    # @param json_pointer [String] JSON pointer indicating which parameter to extract.
+    # @return [Object, nil] The initial offset value from the specified parameter, or default if not found.
+    def get_parameter_value_by_json_pointer(json_pointer)
+      param_pointer, field_pointer = JsonPointerHelper.split_into_parts(json_pointer)
+
+      case param_pointer
+      when PATH_PARAM_POINTER
+        JsonPointerHelper.get_value_by_json_pointer(
+          @template_params, "#{field_pointer}/value"
+        )
+      when QUERY_PARAM_POINTER
+        JsonPointerHelper.get_value_by_json_pointer(@query_params, field_pointer)
+      when HEADER_PARAM_POINTER
+        JsonPointerHelper.get_value_by_json_pointer(@header_params, field_pointer)
+      when BODY_PARAM_POINTER
+        JsonPointerHelper.get_value_by_json_pointer(
+          @body_params || @form_params, field_pointer
+        )
+      else
+        nil
+      end
+    end
+
+    # Creates a deep copy of this RequestBuilder instance with optional overrides.
+    #
+    # @param template_params [Hash, nil] Optional replacement for template_params
+    # @param query_params [Hash, nil] Optional replacement for query_params
+    # @param header_params [Hash, nil] Optional replacement for header_params
+    # @param body_params [Object, nil] Optional replacement for body_params
+    # @param form_params [Hash, nil] Optional replacement for form_params
+    #
+    # @return [RequestBuilder] A new instance with copied state and applied overrides
+    def clone_with(
+      template_params: nil,
+      query_params: nil,
+      header_params: nil,
+      body_params: nil,
+      form_params: nil
+    )
+      clone = RequestBuilder.new
+
+      # Manually copy internal state
+      clone.instance_variable_set(:@server, DeepCloneUtils.deep_copy(@server))
+      clone.instance_variable_set(:@path, DeepCloneUtils.deep_copy(@path))
+      clone.instance_variable_set(:@http_method, DeepCloneUtils.deep_copy(@http_method))
+      clone.instance_variable_set(:@template_params, template_params || DeepCloneUtils.deep_copy(@template_params))
+      clone.instance_variable_set(:@header_params, header_params || DeepCloneUtils.deep_copy(@header_params))
+      clone.instance_variable_set(:@query_params, query_params || DeepCloneUtils.deep_copy(@query_params))
+      clone.instance_variable_set(:@form_params, form_params || DeepCloneUtils.deep_copy(@form_params))
+      clone.instance_variable_set(:@additional_form_params, DeepCloneUtils.deep_copy(@additional_form_params))
+      clone.instance_variable_set(:@additional_query_params, DeepCloneUtils.deep_copy(@additional_query_params))
+      clone.instance_variable_set(:@multipart_params, DeepCloneUtils.deep_copy(@multipart_params))
+      clone.instance_variable_set(:@body_params, body_params || DeepCloneUtils.deep_copy(@body_params))
+      clone.instance_variable_set(:@body_serializer, DeepCloneUtils.deep_copy(@body_serializer))
+      clone.instance_variable_set(:@auth, DeepCloneUtils.deep_copy(@auth))
+      clone.instance_variable_set(:@array_serialization_format, DeepCloneUtils.deep_copy(@array_serialization_format))
+      clone.instance_variable_set(:@xml_attributes, DeepCloneUtils.deep_copy(@xml_attributes))
+
+      clone
+    end
   end
 end

data/lib/apimatic-core/response_handler.rb

@@ -16,6 +16,7 @@ module CoreLibrary
       @is_date_response = false
       @is_response_array = false
       @is_response_void = false
+      @is_nullable_response = false
     end
 
     # Sets deserializer for the response.
@@ -85,7 +86,7 @@ module CoreLibrary
     # Sets the is_primitive_response property.
     # @param [Boolean] is_primitive_response Flag if the response is of primitive type.
     # @return [ResponseHandler] An updated instance of ResponseHandler.
-    # rubocop:disable Naming/PredicateName
+    # rubocop:disable Naming/PredicateName, Naming/PredicatePrefix
     def is_primitive_response(is_primitive_response)
       @is_primitive_response = is_primitive_response
       self
@@ -138,7 +139,15 @@ module CoreLibrary
       @is_response_void = is_response_void
       self
     end
-    # rubocop:enable Naming/PredicateName
+
+    # Sets the is_nullable_response property.
+    # @param [Boolean] is_nullable_response Flag to return early in case of empty response payload.
+    # @return [ResponseHandler] An updated instance of ResponseHandler.
+    def is_nullable_response(is_nullable_response)
+      @is_nullable_response = is_nullable_response
+      self
+    end
+    # rubocop:enable Naming/PredicateName, Naming/PredicatePrefix
 
     # Main method to handle the response with all the set properties.
     # @param [HttpResponse] response The response received.
@@ -152,7 +161,7 @@ module CoreLibrary
       # validating response if configured
       validate(response, global_errors)
 
-      return if @is_response_void
+      return if @is_response_void && !@is_api_response
 
       # applying deserializer if configured
       deserialized_value = apply_deserializer(response, should_symbolize_hash)
@@ -191,6 +200,8 @@ module CoreLibrary
     # Applies deserializer to the response.
     # @param [Boolean] should_symbolize_hash Flag to symbolize the hash during response deserialization.
     def apply_deserializer(response, should_symbolize_hash)
+      return if @is_nullable_response && (response.raw_body.nil? || response.raw_body.to_s.strip.empty?)
+
       return apply_xml_deserializer(response) if @is_xml_response
       return response.raw_body if @deserializer.nil?
 

data/lib/apimatic-core/types/parameter.rb

@@ -45,12 +45,12 @@ module CoreLibrary
     # The setter for the flag if the parameter is required.
     # @param [Boolean] is_required true if the parameter is required otherwise false, by default the value is false.
     # @return [Parameter] An updated instance of Parameter.
-    # rubocop:disable Naming/PredicateName
+    # rubocop:disable Naming/PredicateName, Naming/PredicatePrefix
     def is_required(is_required)
       @is_required = is_required
       self
     end
-    # rubocop:enable Naming/PredicateName
+    # rubocop:enable Naming/PredicateName, Naming/PredicatePrefix
 
     # The setter for the flag if the parameter value is to be encoded.
     # @param [Boolean] should_encode true if the parameter value is to be encoded otherwise false, default is false.

data/lib/apimatic-core/types/sdk/base_model.rb

@@ -16,7 +16,7 @@ module CoreLibrary
 
     # Override for additional model properties.
     def respond_to_missing?(method_sym, include_private = false)
-      instance_variable_defined?("@#{method_sym}") ? true : super
+      instance_variable_defined?("@#{method_sym}") || super
     end
   end
 end

data/lib/apimatic-core/utilities/api_helper.rb

@@ -1,4 +1,6 @@
 require 'erb'
+require 'uri'
+require 'cgi'
 
 module CoreLibrary
   # API utility class involved in executing an API
@@ -290,7 +292,7 @@ module CoreLibrary
     # @return [Hash, Array, nil] The parsed JSON object, or nil if the input string is nil.
     # @raise [TypeError] if the server responds with invalid JSON and primitive type parsing is not allowed.
     def self.json_deserialize(json, should_symbolize = false, allow_primitive_type_parsing = false)
-      return if json.nil?
+      return if json.nil? || json.to_s.strip.empty?
 
       begin
         JSON.parse(json, symbolize_names: should_symbolize)
@@ -375,12 +377,12 @@ module CoreLibrary
     def self.form_encode(obj, instance_name, formatting: ArraySerializationFormat::INDEXED)
       retval = {}
 
-      # If this is a structure, resolve it's field names.
+      # If this is a structure, resolve its field names.
       obj = obj.to_hash if obj.is_a? BaseModel
 
       # Create a form encoded hash for this object.
       if obj.nil?
-        nil
+        return retval
       elsif obj.instance_of? Array
         if formatting == ArraySerializationFormat::INDEXED
           obj.each_with_index do |value, index|
@@ -415,6 +417,7 @@ module CoreLibrary
       else
         retval[instance_name] = obj
       end
+
       retval
     end
 
@@ -442,6 +445,73 @@ module CoreLibrary
       val
     end
 
+    # Apply unboxing_function to additional properties from hash.
+    # @param [Hash] hash The hash to extract additional properties from.
+    # @param [Proc] unboxing_function The deserializer to apply to each item in the hash.
+    # @return [Hash] A hash containing the additional properties and their values.
+    def self.get_additional_properties(hash, unboxing_function, is_array: false, is_dict: false, is_array_of_map: false,
+                                       is_map_of_array: false, dimension_count: 1)
+      additional_properties = {}
+
+      # Iterate over each key-value pair in the input hash
+      hash.each do |key, value|
+        # Prepare arguments for apply_unboxing_function
+        args = {
+          is_array: is_array,
+          is_dict: is_dict,
+          is_array_of_map: is_array_of_map,
+          is_map_of_array: is_map_of_array,
+          dimension_count: dimension_count
+        }
+
+        # If the value is a complex structure (Hash or Array), apply apply_unboxing_function
+        additional_properties[key] = if is_array || is_dict
+                                       apply_unboxing_function(value, unboxing_function, **args)
+                                     else
+                                       # Apply the unboxing function directly for simple values
+                                       unboxing_function.call(value)
+                                     end
+      rescue StandardError
+        # Ignore the exception and continue processing
+      end
+
+      additional_properties
+    end
+
+    def self.apply_unboxing_function(obj, unboxing_function, is_array: false, is_dict: false, is_array_of_map: false,
+                                     is_map_of_array: false, dimension_count: 1)
+      if is_dict
+        if is_map_of_array
+          # Handle case where the object is a map of arrays (Hash with array values)
+          obj.transform_values do |v|
+            apply_unboxing_function(v, unboxing_function, is_array: true, dimension_count: dimension_count)
+          end
+        else
+          # Handle regular Hash (map) case
+          obj.transform_values { |v| unboxing_function.call(v) }
+        end
+      elsif is_array
+        if is_array_of_map
+          # Handle case where the object is an array of maps (Array of Hashes)
+          obj.map do |element|
+            apply_unboxing_function(element, unboxing_function, is_dict: true, dimension_count: dimension_count)
+          end
+        elsif dimension_count > 1
+          # Handle multi-dimensional array
+          obj.map do |element|
+            apply_unboxing_function(element, unboxing_function, is_array: true,
+                                                                dimension_count: dimension_count - 1)
+          end
+        else
+          # Handle regular Array case
+          obj.map { |element| unboxing_function.call(element) }
+        end
+      else
+        # Handle base case where the object is neither Array nor Hash
+        unboxing_function.call(obj)
+      end
+    end
+
     # Get content-type depending on the value
     # @param [Object] value The value for which the content-type is resolved.
     def self.get_content_type(value)
@@ -476,7 +546,7 @@ module CoreLibrary
         if placeholder.include? '#'
           # pick the 2nd chunk then remove the last character (i.e. `}`) of the string value
           node_pointer = placeholder.split('#')[1].delete_suffix('}')
-          value_pointer = JsonPointerHelper.new(value, node_pointer, symbolize_keys: true)
+          value_pointer = JsonPointer.new(value, node_pointer, symbolize_keys: true)
           extracted_value = json_serialize(value_pointer.value) if value_pointer.exists?
         elsif !value.nil?
           extracted_value = json_serialize(value)
@@ -513,5 +583,41 @@ module CoreLibrary
 
       template
     end
+
+    # Parses query parameters from a given URL.
+    # Returns a Hash with decoded keys and values.
+    # If a key has multiple values, they are returned as an array.
+    #
+    # Example:
+    #   ApiHelper.get_query_parameters("https://example.com?a=1&b=2&b=3")
+    #   => {"a"=>"1", "b"=>["2", "3"]}
+    def self.get_query_parameters(url)
+      return {} if url.nil? || url.strip.empty?
+
+      begin
+        uri = URI.parse(url)
+        query = uri.query
+        return {} if query.nil? || query.strip.empty?
+
+        parsed = CGI.parse(query)
+
+        # Convert arrays to string or handle empty ones as ""
+        parsed.transform_values! do |v|
+          if v.empty?
+            ''
+          elsif v.size == 1
+            v.first
+          else
+            v
+          end
+        end
+      rescue URI::InvalidURIError => e
+        warn "Invalid URL provided: #{e.message}"
+        {}
+      rescue StandardError => e
+        warn "Unexpected error while parsing URL: #{e.message}"
+        {}
+      end
+    end
   end
 end

data/lib/apimatic-core/utilities/deep_clone_utils.rb

@@ -0,0 +1,114 @@
+module CoreLibrary
+  # DeepCloneUtils provides utility methods for performing deep copies of various Ruby objects.
+  #
+  # It supports deep copying of arrays (including nested arrays), hashes (with nested keys/values),
+  # and arbitrary objects. For custom objects, it attempts to use the `deep_copy` method if defined;
+  # otherwise, it falls back to using `dup` with error handling.
+  #
+  # The implementation also keeps track of already visited objects using identity-based hashing
+  # to safely handle circular references and avoid redundant cloning.
+  #
+  # Example usage:
+  #   original = { foo: [1, 2, { bar: 3 }] }
+  #   copy = CoreLibrary::DeepCloneUtils.deep_copy(original)
+  #
+  #   copy[:foo][2][:bar] = 99
+  #   puts original[:foo][2][:bar] # => 3 (remains unchanged)
+  class DeepCloneUtils
+    class << self
+      # Deep copy any value with support for arrays, hashes, and custom deep_copy methods.
+      #
+      # @param value [Object] The value to deeply clone.
+      # @param visited [Hash] A hash that tracks already visited objects to handle cycles.
+      # @return [Object] A deep copy of the input value.
+      def deep_copy(value, visited = {}.compare_by_identity)
+        return value if primitive?(value)
+        return visited[value] if visited.key?(value)
+
+        result = case value
+                 when Array
+                   deep_copy_array(value, visited)
+                 when Hash
+                   deep_copy_hash(value, visited)
+                 else
+                   deep_copy_object(value)
+                 end
+
+        visited[value] = result
+        result
+      end
+
+      # Deep copy a plain array (supports n-dimensional arrays).
+      #
+      # @param array [Array] The array to deeply clone.
+      # @param visited [Hash] Identity hash to track visited objects.
+      # @return [Array] A deep copy of the array.
+      def deep_copy_array(array, visited = {}.compare_by_identity)
+        return nil if array.nil?
+        return array if primitive?(array)
+
+        visited[array] = array_clone = []
+
+        array.each do |item|
+          array_clone << deep_copy(item, visited)
+        end
+
+        array_clone
+      end
+
+      # Deep copy a hash (map), including nested maps.
+      #
+      # @param hash [Hash] The hash to deeply clone.
+      # @param visited [Hash] Identity hash to track visited objects.
+      # @return [Hash] A deep copy of the hash.
+      def deep_copy_hash(hash, visited = {}.compare_by_identity)
+        return nil if hash.nil?
+        return hash if primitive?(hash)
+
+        visited[hash] = hash_clone = {}
+
+        hash.each do |key, value|
+          # Keys are usually immutable, but still cloned for safety
+          key_copy = primitive?(key) ? key : deep_copy(key, visited)
+          hash_clone[key_copy] = deep_copy(value, visited)
+        end
+
+        hash_clone
+      end
+
+      private
+
+      # Deep copy any non-collection object.
+      #
+      # @param obj [Object] The object to deeply clone.
+      # @return [Object] A deep copy of the object.
+      def deep_copy_object(obj)
+        return obj if obj.nil?
+
+        if obj.respond_to?(:deep_copy)
+          obj.deep_copy
+        elsif obj.respond_to?(:dup)
+          begin
+            obj.dup
+          rescue TypeError
+            obj
+          end
+        else
+          obj
+        end
+      end
+
+      # Identify values that do not need deep copy.
+      #
+      # @param value [Object] The value to check.
+      # @return [Boolean] Whether the value is primitive.
+      def primitive?(value)
+        value.is_a?(Numeric) ||
+          value.is_a?(Symbol) ||
+          value.is_a?(TrueClass) ||
+          value.is_a?(FalseClass) ||
+          value.nil?
+      end
+    end
+  end
+end