multi_json 1.18.0 → 1.19.0

data/lib/multi_json/adapter_error.rb

@@ -1,13 +1,33 @@
 module MultiJson
+  # Raised when an adapter cannot be loaded or is not recognized
+  #
+  # @api public
   class AdapterError < ArgumentError
+    # Create a new AdapterError
+    #
+    # @api public
+    # @param message [String, nil] error message
+    # @param cause [Exception, nil] the original exception
+    # @return [AdapterError] new error instance
+    # @example
+    #   AdapterError.new("Unknown adapter", cause: original_error)
     def initialize(message = nil, cause: nil)
       super(message)
       set_backtrace(cause.backtrace) if cause
     end
 
+    # Build an AdapterError from an original exception
+    #
+    # @api public
+    # @param original_exception [Exception] the original load error
+    # @return [AdapterError] new error with formatted message
+    # @example
+    #   AdapterError.build(LoadError.new("cannot load such file"))
     def self.build(original_exception)
-      message = "Did not recognize your adapter specification (#{original_exception.message})."
-      new(message, cause: original_exception)
+      new(
+        "Did not recognize your adapter specification (#{original_exception.message}).",
+        cause: original_exception
+      )
     end
   end
 end

data/lib/multi_json/adapter_selector.rb

@@ -0,0 +1,142 @@
+module MultiJson
+  # Handles adapter discovery, loading, and selection
+  #
+  # Adapters can be specified as:
+  # - Symbol/String: adapter name (e.g., :oj, "json_gem")
+  # - Module: adapter class directly
+  # - nil/false: use default adapter
+  #
+  # @api private
+  module AdapterSelector
+    extend self
+
+    # Alternate spellings for adapter names
+    ALIASES = {"jrjackson" => "jr_jackson"}.freeze
+
+    # Strategy lambdas for loading adapters based on specification type
+    LOADERS = {
+      Module => ->(adapter, _selector) { adapter },
+      String => ->(name, selector) { selector.send(:load_adapter_by_name, name) },
+      Symbol => ->(name, selector) { selector.send(:load_adapter_by_name, name.to_s) },
+      NilClass => ->(_adapter, selector) { selector.send(:load_adapter, selector.default_adapter) },
+      FalseClass => ->(_adapter, selector) { selector.send(:load_adapter, selector.default_adapter) }
+    }.freeze
+
+    # Returns the default adapter to use
+    #
+    # @api private
+    # @return [Symbol] adapter name
+    # @example
+    #   AdapterSelector.default_adapter  #=> :oj
+    def default_adapter
+      @default_adapter ||= detect_best_adapter
+    end
+
+    private
+
+    # Detects the best available JSON adapter
+    #
+    # @api private
+    # @return [Symbol] adapter name
+    def detect_best_adapter
+      loaded_adapter || installable_adapter || fallback_adapter
+    end
+
+    # Finds an already-loaded JSON library
+    #
+    # @api private
+    # @return [Symbol, nil] adapter name if found
+    def loaded_adapter
+      return :fast_jsonparser if defined?(::FastJsonparser)
+      return :oj if defined?(::Oj)
+      return :yajl if defined?(::Yajl)
+      return :jr_jackson if defined?(::JrJackson)
+      return :json_gem if defined?(::JSON::Ext::Parser)
+
+      :gson if defined?(::Gson)
+    end
+
+    # Tries to require and use an installable adapter
+    #
+    # @api private
+    # @return [Symbol, nil] adapter name if successfully required
+    def installable_adapter
+      ::MultiJson::REQUIREMENT_MAP.each_key do |adapter_name|
+        return adapter_name if try_require(adapter_name)
+      end
+      nil
+    end
+
+    # Attempts to require a JSON library
+    #
+    # @api private
+    # @param adapter_name [Symbol] adapter to require
+    # @return [Boolean] true if require succeeded
+    def try_require(adapter_name)
+      require ::MultiJson::REQUIREMENT_MAP.fetch(adapter_name)
+      true
+    rescue ::LoadError
+      false
+    end
+
+    # Returns the fallback adapter when no others available
+    #
+    # @api private
+    # @return [Symbol] the ok_json adapter name
+    def fallback_adapter
+      warn_about_fallback unless @default_adapter_warning_shown
+      @default_adapter_warning_shown = true
+      :ok_json
+    end
+
+    # Warns the user about using the slow fallback adapter
+    #
+    # @api private
+    # @return [void]
+    def warn_about_fallback
+      Kernel.warn(
+        "[WARNING] MultiJson is using the default adapter (ok_json). " \
+        "We recommend loading a different JSON library to improve performance."
+      )
+    end
+
+    # Loads an adapter from a specification
+    #
+    # @api private
+    # @param adapter_spec [Symbol, String, Module, nil] adapter specification
+    # @return [Class] the adapter class
+    def load_adapter(adapter_spec)
+      loader = find_loader_for(adapter_spec)
+      return loader.call(adapter_spec, self) if loader
+
+      raise ::LoadError, adapter_spec
+    rescue ::LoadError => e
+      raise AdapterError.build(e)
+    end
+
+    # Finds the appropriate loader for an adapter specification
+    #
+    # @api private
+    # @param adapter_spec [Object] adapter specification
+    # @return [Proc, nil] loader proc if found
+    def find_loader_for(adapter_spec)
+      klass = adapter_spec.class
+      return LOADERS.fetch(klass) if LOADERS.key?(klass)
+
+      LOADERS.fetch(Module) if adapter_spec.is_a?(Module)
+    end
+
+    # Loads an adapter by its string name
+    #
+    # @api private
+    # @param name [String] adapter name
+    # @return [Class] the adapter class
+    def load_adapter_by_name(name)
+      normalized = ALIASES.fetch(name, name).downcase
+      require_relative "adapters/#{normalized}"
+
+      class_name = normalized.split("_").map(&:capitalize).join
+      ::MultiJson::Adapters.const_get(class_name)
+    end
+  end
+end

data/lib/multi_json/adapters/fast_jsonparser.rb

@@ -0,0 +1,44 @@
+require "fast_jsonparser"
+require "oj"
+require_relative "../adapter"
+require_relative "oj_common"
+
+module MultiJson
+  module Adapters
+    # Use the FastJsonparser library to load and Oj to dump.
+    class FastJsonparser < Adapter
+      include OjCommon
+
+      defaults :load, symbolize_keys: false
+      defaults :dump, mode: :compat, time_format: :ruby, use_to_json: true
+
+      ParseError = ::FastJsonparser::ParseError
+
+      # Parse a JSON string into a Ruby object
+      #
+      # @api private
+      # @param string [String] JSON string to parse
+      # @param options [Hash] parsing options
+      # @return [Object] parsed Ruby object
+      #
+      # @example Parse JSON string
+      #   adapter.load('{"key":"value"}') #=> {"key" => "value"}
+      def load(string, options = {})
+        ::FastJsonparser.parse(string, symbolize_keys: options[:symbolize_keys])
+      end
+
+      # Serialize a Ruby object to JSON
+      #
+      # @api private
+      # @param object [Object] object to serialize
+      # @param options [Hash] serialization options
+      # @return [String] JSON string
+      #
+      # @example Serialize object to JSON
+      #   adapter.dump({key: "value"}) #=> '{"key":"value"}'
+      def dump(object, options = {})
+        ::Oj.dump(object, prepare_dump_options(options))
+      end
+    end
+  end
+end

data/lib/multi_json/adapters/gson.rb

@@ -7,10 +7,28 @@ module MultiJson
     class Gson < Adapter
       ParseError = ::Gson::DecodeError
 
+      # Parse a JSON string into a Ruby object
+      #
+      # @api private
+      # @param string [String] JSON string to parse
+      # @param options [Hash] parsing options
+      # @return [Object] parsed Ruby object
+      #
+      # @example Parse JSON string
+      #   adapter.load('{"key":"value"}') #=> {"key" => "value"}
       def load(string, options = {})
         ::Gson::Decoder.new(options).decode(string)
       end
 
+      # Serialize a Ruby object to JSON
+      #
+      # @api private
+      # @param object [Object] object to serialize
+      # @param options [Hash] serialization options
+      # @return [String] JSON string
+      #
+      # @example Serialize object to JSON
+      #   adapter.dump({key: "value"}) #=> '{"key":"value"}'
       def dump(object, options = {})
         ::Gson::Encoder.new(options).encode(object)
       end

data/lib/multi_json/adapters/jr_jackson.rb

@@ -7,15 +7,42 @@ module MultiJson
     class JrJackson < Adapter
       ParseError = ::JrJackson::ParseError
 
-      def load(string, options = {}) # :nodoc:
+      # Parse a JSON string into a Ruby object
+      #
+      # @api private
+      # @param string [String] JSON string to parse
+      # @param options [Hash] parsing options
+      # @return [Object] parsed Ruby object
+      #
+      # @example Parse JSON string
+      #   adapter.load('{"key":"value"}') #=> {"key" => "value"}
+      def load(string, options = {})
         ::JrJackson::Json.load(string, options)
       end
 
       if ::JrJackson::Json.method(:dump).arity == 1
+        # Serialize a Ruby object to JSON
+        #
+        # @api private
+        # @param object [Object] object to serialize
+        # @param _ [Hash] serialization options (unused in this version)
+        # @return [String] JSON string
+        #
+        # @example Serialize object to JSON
+        #   adapter.dump({key: "value"}) #=> '{"key":"value"}'
         def dump(object, _)
           ::JrJackson::Json.dump(object)
         end
       else
+        # Serialize a Ruby object to JSON
+        #
+        # @api private
+        # @param object [Object] object to serialize
+        # @param options [Hash] serialization options
+        # @return [String] JSON string
+        #
+        # @example Serialize object to JSON
+        #   adapter.dump({key: "value"}) #=> '{"key":"value"}'
         def dump(object, options = {})
           ::JrJackson::Json.dump(object, options)
         end

data/lib/multi_json/adapters/json_gem.rb

@@ -17,6 +17,15 @@ module MultiJson
       }.freeze
       private_constant :PRETTY_STATE_PROTOTYPE
 
+      # Parse a JSON string into a Ruby object
+      #
+      # @api private
+      # @param string [String] JSON string to parse
+      # @param options [Hash] parsing options
+      # @return [Object] parsed Ruby object
+      #
+      # @example Parse JSON string
+      #   adapter.load('{"key":"value"}') #=> {"key" => "value"}
       def load(string, options = {})
         string = string.dup.force_encoding(Encoding::UTF_8) if string.encoding != Encoding::UTF_8
 
@@ -24,15 +33,26 @@ module MultiJson
         ::JSON.parse(string, options)
       end
 
+      # Serialize a Ruby object to JSON
+      #
+      # @api private
+      # @param object [Object] object to serialize
+      # @param options [Hash] serialization options
+      # @return [String] JSON string
+      #
+      # @example Serialize object to JSON
+      #   adapter.dump({key: "value"}) #=> '{"key":"value"}'
       def dump(object, options = {})
-        opts = options.dup
+        opts = options.except(:adapter)
+        json_object = object.respond_to?(:as_json) ? object.as_json : object
+        return ::JSON.dump(json_object) if opts.empty?
 
         if opts.delete(:pretty)
           opts = PRETTY_STATE_PROTOTYPE.merge(opts)
-          return ::JSON.pretty_generate(object, opts)
+          return ::JSON.pretty_generate(json_object, opts)
         end
 
-        ::JSON.generate(object, opts)
+        ::JSON.generate(json_object, opts)
       end
     end
   end

data/lib/multi_json/adapters/oj.rb

@@ -1,10 +1,13 @@
 require "oj"
 require_relative "../adapter"
+require_relative "oj_common"
 
 module MultiJson
   module Adapters
     # Use the Oj library to dump/load.
     class Oj < Adapter
+      include OjCommon
+
       defaults :load, mode: :strict, symbolize_keys: false
       defaults :dump, mode: :compat, time_format: :ruby, use_to_json: true
 
@@ -19,44 +22,44 @@ module MultiJson
         WRAPPED_CLASSES = %w[Oj::ParseError JSON::ParserError].freeze
         private_constant :WRAPPED_CLASSES
 
+        # Case equality for exception matching in rescue clauses
+        #
+        # @api private
+        # @param exception [Exception] exception to check
+        # @return [Boolean] true if exception is a parse error
+        #
+        # @example Match parse errors in rescue
+        #   rescue ParseError => e
         def self.===(exception)
           exception.is_a?(::SyntaxError) || WRAPPED_CLASSES.include?(exception.class.to_s)
         end
       end
 
+      # Parse a JSON string into a Ruby object
+      #
+      # @api private
+      # @param string [String] JSON string to parse
+      # @param options [Hash] parsing options
+      # @return [Object] parsed Ruby object
+      #
+      # @example Parse JSON string
+      #   adapter.load('{"key":"value"}') #=> {"key" => "value"}
       def load(string, options = {})
         options[:symbol_keys] = options[:symbolize_keys]
         ::Oj.load(string, options)
       end
 
-      OJ_VERSION = ::Oj::VERSION
-      OJ_V2 = OJ_VERSION.start_with?("2.")
-      OJ_V3 = OJ_VERSION.start_with?("3.")
-      private_constant :OJ_VERSION, :OJ_V2, :OJ_V3
-
-      if OJ_V3
-        PRETTY_STATE_PROTOTYPE = {
-          indent: "  ",
-          space: " ",
-          space_before: "",
-          object_nl: "\n",
-          array_nl: "\n",
-          ascii_only: false
-        }.freeze
-        private_constant :PRETTY_STATE_PROTOTYPE
-      end
-
+      # Serialize a Ruby object to JSON
+      #
+      # @api private
+      # @param object [Object] object to serialize
+      # @param options [Hash] serialization options
+      # @return [String] JSON string
+      #
+      # @example Serialize object to JSON
+      #   adapter.dump({key: "value"}) #=> '{"key":"value"}'
       def dump(object, options = {})
-        if OJ_V2
-          options[:indent] = 2 if options[:pretty]
-          options[:indent] = options[:indent].to_i if options[:indent]
-        elsif OJ_V3
-          options.merge!(PRETTY_STATE_PROTOTYPE.dup) if options.delete(:pretty)
-        else
-          raise "Unsupported Oj version: #{::Oj::VERSION}"
-        end
-
-        ::Oj.dump(object, options)
+        ::Oj.dump(object, prepare_dump_options(options))
       end
     end
   end

data/lib/multi_json/adapters/oj_common.rb

@@ -0,0 +1,47 @@
+require "rubygems/version"
+
+module MultiJson
+  module Adapters
+    module OjCommon
+      OJ_VERSION = Gem::Version.new(::Oj::VERSION)
+      OJ_V2 = OJ_VERSION.segments.first == 2
+      OJ_V3 = OJ_VERSION.segments.first == 3
+      private_constant :OJ_VERSION, :OJ_V2, :OJ_V3
+
+      if OJ_V3
+        PRETTY_STATE_PROTOTYPE = {
+          indent: "  ",
+          space: " ",
+          space_before: "",
+          object_nl: "\n",
+          array_nl: "\n",
+          ascii_only: false
+        }.freeze
+        private_constant :PRETTY_STATE_PROTOTYPE
+      end
+
+      private
+
+      # Prepare options for Oj.dump based on Oj version
+      #
+      # @api private
+      # @param options [Hash] serialization options
+      # @return [Hash] processed options for Oj.dump
+      #
+      # @example Prepare dump options
+      #   prepare_dump_options(pretty: true)
+      def prepare_dump_options(options)
+        if OJ_V2
+          options[:indent] = 2 if options[:pretty]
+          options[:indent] = options[:indent].to_i if options[:indent]
+        elsif OJ_V3
+          options.merge!(PRETTY_STATE_PROTOTYPE.dup) if options.delete(:pretty)
+        else
+          raise "Unsupported Oj version: #{::Oj::VERSION}"
+        end
+
+        options
+      end
+    end
+  end
+end

data/lib/multi_json/adapters/ok_json.rb

@@ -4,11 +4,21 @@ require_relative "../vendor/okjson"
 
 module MultiJson
   module Adapters
+    # Use the vendored OkJson library to dump/load.
     class OkJson < Adapter
       include ConvertibleHashKeys
 
       ParseError = ::MultiJson::OkJson::Error
 
+      # Parse a JSON string into a Ruby object
+      #
+      # @api private
+      # @param string [String] JSON string to parse
+      # @param options [Hash] parsing options
+      # @return [Object] parsed Ruby object
+      #
+      # @example Parse JSON string
+      #   adapter.load('{"key":"value"}') #=> {"key" => "value"}
       def load(string, options = {})
         result = ::MultiJson::OkJson.decode("[#{string}]").first
         options[:symbolize_keys] ? symbolize_keys(result) : result
@@ -16,6 +26,15 @@ module MultiJson
         raise ParseError
       end
 
+      # Serialize a Ruby object to JSON
+      #
+      # @api private
+      # @param object [Object] object to serialize
+      # @param _ [Hash] serialization options (unused)
+      # @return [String] JSON string
+      #
+      # @example Serialize object to JSON
+      #   adapter.dump({key: "value"}) #=> '{"key":"value"}'
       def dump(object, _ = {})
         ::MultiJson::OkJson.valenc(stringify_keys(object))
       end

data/lib/multi_json/adapters/yajl.rb

@@ -7,10 +7,28 @@ module MultiJson
     class Yajl < Adapter
       ParseError = ::Yajl::ParseError
 
+      # Parse a JSON string into a Ruby object
+      #
+      # @api private
+      # @param string [String] JSON string to parse
+      # @param options [Hash] parsing options
+      # @return [Object] parsed Ruby object
+      #
+      # @example Parse JSON string
+      #   adapter.load('{"key":"value"}') #=> {"key" => "value"}
       def load(string, options = {})
         ::Yajl::Parser.new(symbolize_keys: options[:symbolize_keys]).parse(string)
       end
 
+      # Serialize a Ruby object to JSON
+      #
+      # @api private
+      # @param object [Object] object to serialize
+      # @param options [Hash] serialization options
+      # @return [String] JSON string
+      #
+      # @example Serialize object to JSON
+      #   adapter.dump({key: "value"}) #=> '{"key":"value"}'
       def dump(object, options = {})
         ::Yajl::Encoder.encode(object, options)
       end

data/lib/multi_json/convertible_hash_keys.rb

@@ -1,49 +1,64 @@
 module MultiJson
+  # Mixin for converting hash keys between symbols and strings
+  #
+  # @api private
   module ConvertibleHashKeys
     SIMPLE_OBJECT_CLASSES = [String, Numeric, TrueClass, FalseClass, NilClass].freeze
     private_constant :SIMPLE_OBJECT_CLASSES
 
     private
 
-    def symbolize_keys(hash)
-      prepare_hash(hash) do |key|
-        key.respond_to?(:to_sym) ? key.to_sym : key
-      end
+    # Converts hash keys to symbols recursively
+    #
+    # @api private
+    # @param value [Object] value to convert
+    # @return [Object] value with symbolized keys
+    def symbolize_keys(value)
+      convert_hash_keys(value) { |key| key.respond_to?(:to_sym) ? key.to_sym : key }
     end
 
-    def stringify_keys(hash)
-      prepare_hash(hash) do |key|
-        key.respond_to?(:to_s) ? key.to_s : key
-      end
+    # Converts hash keys to strings recursively
+    #
+    # @api private
+    # @param value [Object] value to convert
+    # @return [Object] value with stringified keys
+    def stringify_keys(value)
+      convert_hash_keys(value) { |key| key.respond_to?(:to_s) ? key.to_s : key }
     end
 
-    def prepare_hash(value, &block)
+    # Recursively converts hash keys using the given block
+    #
+    # @api private
+    # @param value [Object] value to convert
+    # @yield [key] block to transform each key
+    # @return [Object] converted value
+    def convert_hash_keys(value, &key_modifier)
       case value
-      when Array
-        handle_array(value, &block)
       when Hash
-        handle_hash(value, &block)
+        value.to_h { |k, v| [key_modifier.call(k), convert_hash_keys(v, &key_modifier)] }
+      when Array
+        value.map { |v| convert_hash_keys(v, &key_modifier) }
       else
-        handle_simple_objects(value)
+        convert_simple_object(value)
       end
     end
 
-    def handle_simple_objects(obj)
+    # Converts non-hash objects to a JSON-safe format
+    #
+    # @api private
+    # @param obj [Object] object to convert
+    # @return [Object] converted object
+    def convert_simple_object(obj)
       return obj if simple_object?(obj) || obj.respond_to?(:to_json)
 
       obj.respond_to?(:to_s) ? obj.to_s : obj
     end
 
-    def handle_array(array, &key_modifier)
-      array.map { |value| prepare_hash(value, &key_modifier) }
-    end
-
-    def handle_hash(original_hash, &key_modifier)
-      original_hash.each_with_object({}) do |(key, value), result|
-        result[key_modifier.call(key)] = prepare_hash(value, &key_modifier)
-      end
-    end
-
+    # Checks if an object is a simple JSON-safe type
+    #
+    # @api private
+    # @param obj [Object] object to check
+    # @return [Boolean] true if object is a simple type
     def simple_object?(obj)
       SIMPLE_OBJECT_CLASSES.any? { |klass| obj.is_a?(klass) }
     end