multi_json 1.18.0 → 1.19.0

data/lib/multi_json/options.rb

@@ -1,49 +1,86 @@
 module MultiJson
+  # Mixin providing configurable load/dump options
+  #
+  # Supports static hashes or dynamic callables (procs/lambdas).
+  # Extended by both MultiJson (global options) and Adapter classes.
+  #
+  # @api private
   module Options
+    EMPTY_OPTIONS = {}.freeze
+    private_constant :EMPTY_OPTIONS
+
+    # Set options for load operations
+    #
+    # @api private
+    # @param options [Hash, Proc] options hash or callable
+    # @return [Hash, Proc] the options
     def load_options=(options)
       OptionsCache.reset
       @load_options = options
     end
 
+    # Set options for dump operations
+    #
+    # @api private
+    # @param options [Hash, Proc] options hash or callable
+    # @return [Hash, Proc] the options
     def dump_options=(options)
       OptionsCache.reset
       @dump_options = options
     end
 
-    def load_options(*args)
-      (defined?(@load_options) && get_options(@load_options, *args)) || default_load_options
+    # Get options for load operations
+    #
+    # @api private
+    # @return [Hash] resolved options hash
+    def load_options(...)
+      resolve_options(@load_options, ...) || default_load_options
     end
 
-    def dump_options(*args)
-      (defined?(@dump_options) && get_options(@dump_options, *args)) || default_dump_options
+    # Get options for dump operations
+    #
+    # @api private
+    # @return [Hash] resolved options hash
+    def dump_options(...)
+      resolve_options(@dump_options, ...) || default_dump_options
     end
 
+    # Get default load options
+    #
+    # @api private
+    # @return [Hash] frozen empty hash
     def default_load_options
-      @default_load_options ||= {}.freeze
+      @default_load_options ||= EMPTY_OPTIONS
     end
 
+    # Get default dump options
+    #
+    # @api private
+    # @return [Hash] frozen empty hash
     def default_dump_options
-      @default_dump_options ||= {}.freeze
+      @default_dump_options ||= EMPTY_OPTIONS
     end
 
     private
 
-    def get_options(options, *args)
-      return handle_callable_options(options, *args) if options_callable?(options)
-
-      handle_hashable_options(options)
-    end
-
-    def options_callable?(options)
-      options.respond_to?(:call)
-    end
+    # Resolves options from a hash or callable
+    #
+    # @api private
+    # @param options [Hash, Proc, nil] options configuration
+    # @return [Hash, nil] resolved options hash
+    def resolve_options(options, ...)
+      return invoke_callable(options, ...) if options.respond_to?(:call)
 
-    def handle_callable_options(options, *args)
-      options.arity.zero? ? options.call : options.call(*args)
+      options.to_hash if options.respond_to?(:to_hash)
     end
 
-    def handle_hashable_options(options)
-      options.respond_to?(:to_hash) ? options.to_hash : nil
+    # Invokes a callable options provider
+    #
+    # @api private
+    # @param callable [Proc] options provider
+    # @return [Hash] options returned by the callable
+    def invoke_callable(callable, ...)
+      callable.arity.zero? ? callable.call : callable.call(...)
     end
   end
 end

data/lib/multi_json/options_cache.rb

@@ -1,47 +1,92 @@
 module MultiJson
+  # Thread-safe LRU-like cache for merged options hashes
+  #
+  # Caches are separated for load and dump operations. Each cache is
+  # bounded to prevent unbounded memory growth when options are
+  # generated dynamically.
+  #
+  # @api private
   module OptionsCache
+    # Maximum entries before oldest entry is evicted
+    MAX_CACHE_SIZE = 1000
+
+    # Thread-safe cache store using double-checked locking pattern
+    #
+    # @api private
     class Store
-      # Normally MultiJson is used with a few option sets for both dump/load
-      # methods. When options are generated dynamically though, every call would
-      # cause a cache miss and the cache would grow indefinitely. To prevent
-      # this, we just reset the cache every time the number of keys outgrows
-      # 1000.
-      MAX_CACHE_SIZE = 1000
-      private_constant :MAX_CACHE_SIZE
+      # Sentinel value to detect cache misses (unique object identity)
+      NOT_FOUND = Object.new
 
+      # Create a new cache store
+      #
+      # @api private
+      # @return [Store] new store instance
       def initialize
         @cache = {}
         @mutex = Mutex.new
       end
 
+      # Clear all cached entries
+      #
+      # @api private
+      # @return [void]
       def reset
-        @mutex.synchronize do
-          @cache = {}
-        end
+        @mutex.synchronize { @cache.clear }
       end
 
-      def fetch(key)
+      # Fetch a value from cache or compute it
+      #
+      # @api private
+      # @param key [Object] cache key
+      # @param default [Object] default value if key not found
+      # @yield block to compute value if not cached
+      # @return [Object] cached or computed value
+      def fetch(key, default = nil)
+        # Fast path: check cache without lock (safe for reads)
+        value = @cache.fetch(key, NOT_FOUND)
+        return value unless value.equal?(NOT_FOUND)
+
+        # Slow path: acquire lock and compute value
         @mutex.synchronize do
-          return @cache[key] if @cache.key?(key)
+          @cache.fetch(key) { block_given? ? store(key, yield) : default }
         end
+      end
 
-        value = yield
+      private
 
-        @mutex.synchronize do
-          if @cache.key?(key)
-            # We ran into a race condition, keep the existing value
-            @cache[key]
-          else
-            @cache.clear if @cache.size >= MAX_CACHE_SIZE
-            @cache[key] = value
-          end
+      # Stores a value in the cache with LRU eviction
+      #
+      # @api private
+      # @param key [Object] cache key
+      # @param value [Object] value to store
+      # @return [Object] the stored value
+      def store(key, value)
+        # Double-check in case another thread computed while we waited
+        @cache.fetch(key) do
+          # Evict oldest entry if at capacity (Hash maintains insertion order)
+          @cache.shift if @cache.size >= MAX_CACHE_SIZE
+          @cache[key] = value
         end
       end
     end
 
     class << self
-      attr_reader :dump, :load
+      # Get the dump options cache
+      #
+      # @api private
+      # @return [Store] dump cache store
+      attr_reader :dump
+
+      # Get the load options cache
+      #
+      # @api private
+      # @return [Store] load cache store
+      attr_reader :load
 
+      # Reset both caches
+      #
+      # @api private
+      # @return [void]
       def reset
         @dump = Store.new
         @load = Store.new

data/lib/multi_json/parse_error.rb

@@ -1,17 +1,46 @@
 module MultiJson
+  # Raised when JSON parsing fails
+  #
+  # Wraps the underlying adapter's parse error with the original input data.
+  #
+  # @api public
   class ParseError < StandardError
+    # The input string that failed to parse
+    #
+    # @api public
+    # @return [String, nil] the original input data
+    # @example
+    #   error.data  #=> "{invalid json}"
     attr_reader :data
 
+    # Create a new ParseError
+    #
+    # @api public
+    # @param message [String, nil] error message
+    # @param data [String, nil] the input that failed to parse
+    # @param cause [Exception, nil] the original exception
+    # @return [ParseError] new error instance
+    # @example
+    #   ParseError.new("unexpected token", data: "{invalid}", cause: err)
     def initialize(message = nil, data: nil, cause: nil)
       super(message)
       @data = data
       set_backtrace(cause.backtrace) if cause
     end
 
+    # Build a ParseError from an original exception
+    #
+    # @api public
+    # @param original_exception [Exception] the adapter's parse error
+    # @param data [String] the input that failed to parse
+    # @return [ParseError] new error with formatted message
+    # @example
+    #   ParseError.build(JSON::ParserError.new("..."), "{bad json}")
     def self.build(original_exception, data)
       new(original_exception.message, data: data, cause: original_exception)
     end
   end
 
-  DecodeError = LoadError = ParseError # Legacy support
+  # Legacy aliases for backward compatibility
+  DecodeError = LoadError = ParseError
 end

data/lib/multi_json/vendor/okjson.rb

@@ -391,7 +391,7 @@ module MultiJson
     end
 
     def strenc(s)
-      t = StringIO.new
+      t = StringIO.new(String.new(encoding: Encoding::UTF_8))
       t.putc('"')
       r = 0
 

data/lib/multi_json/version.rb

@@ -1,17 +1,28 @@
 module MultiJson
+  # Version information for MultiJson
+  #
+  # @api private
   class Version
+    # Major version number
     MAJOR = 1 unless defined? MultiJson::Version::MAJOR
-    MINOR = 18 unless defined? MultiJson::Version::MINOR
+    # Minor version number
+    MINOR = 19 unless defined? MultiJson::Version::MINOR
+    # Patch version number
     PATCH = 0 unless defined? MultiJson::Version::PATCH
+    # Pre-release version suffix
     PRE = nil unless defined? MultiJson::Version::PRE
 
     class << self
-      # @return [String]
+      # Return the version string
+      #
+      # @api private
+      # @return [String] version in semver format
       def to_s
         [MAJOR, MINOR, PATCH, PRE].compact.join(".")
       end
     end
   end
 
+  # Current version string in semver format
   VERSION = Version.to_s.freeze
 end

data/lib/multi_json.rb

@@ -3,170 +3,229 @@ require_relative "multi_json/version"
 require_relative "multi_json/adapter_error"
 require_relative "multi_json/parse_error"
 require_relative "multi_json/options_cache"
-
+require_relative "multi_json/adapter_selector"
+
+# A unified interface for JSON libraries in Ruby
+#
+# MultiJson allows swapping between JSON backends without changing your code.
+# It auto-detects available JSON libraries and uses the fastest one available.
+#
+# @example Basic usage
+#   MultiJson.load('{"foo":"bar"}')  #=> {"foo" => "bar"}
+#   MultiJson.dump({foo: "bar"})     #=> '{"foo":"bar"}'
+#
+# @example Specifying an adapter
+#   MultiJson.use(:oj)
+#   MultiJson.load('{"foo":"bar"}', adapter: :json_gem)
+#
+# @api public
 module MultiJson
-  include Options
-  extend self
+  extend Options
+  extend AdapterSelector
 
-  def default_options=(value)
-    Kernel.warn "MultiJson.default_options setter is deprecated\nUse MultiJson.load_options and MultiJson.dump_options instead"
+  # @!visibility private
+  module_function
+
+  # @!group Configuration
 
+  # Set default options for both load and dump operations
+  #
+  # @api private
+  # @deprecated Use {.load_options=} and {.dump_options=} instead
+  # @param value [Hash] options hash
+  # @return [Hash] the options hash
+  # @example
+  #   MultiJson.default_options = {symbolize_keys: true}
+  def default_options=(value)
+    Kernel.warn "MultiJson.default_options setter is deprecated\n" \
+                "Use MultiJson.load_options and MultiJson.dump_options instead"
     self.load_options = self.dump_options = value
   end
 
+  # Get the default options
+  #
+  # @api private
+  # @deprecated Use {.load_options} or {.dump_options} instead
+  # @return [Hash] the current load options
+  # @example
+  #   MultiJson.default_options  #=> {}
   def default_options
-    Kernel.warn "MultiJson.default_options is deprecated\nUse MultiJson.load_options or MultiJson.dump_options instead"
-
+    Kernel.warn "MultiJson.default_options is deprecated\n" \
+                "Use MultiJson.load_options or MultiJson.dump_options instead"
     load_options
   end
 
+  # @deprecated These methods are no longer used
   %w[cached_options reset_cached_options!].each do |method_name|
-    define_method method_name do |*|
+    define_method(method_name) do |*|
       Kernel.warn "MultiJson.#{method_name} method is deprecated and no longer used."
     end
   end
 
-  ALIASES = {"jrjackson" => "jr_jackson"}.freeze
+  # Legacy alias for adapter name mappings
+  ALIASES = AdapterSelector::ALIASES
 
+  # Maps adapter symbols to their require paths for auto-loading
   REQUIREMENT_MAP = {
+    fast_jsonparser: "fast_jsonparser",
     oj: "oj",
     yajl: "yajl",
     jr_jackson: "jrjackson",
     json_gem: "json",
-    gson: "gson",
-    json_pure: "json"
+    gson: "gson"
   }.freeze
 
-  # The default adapter based on what you currently
-  # have loaded and installed.
-  def default_adapter
-    adapter = loaded_adapter || installable_adapter
-    return adapter if adapter
-
-    @default_adapter_warning_shown ||= begin
-      Kernel.warn(
-        "[WARNING] MultiJson is using the default adapter (ok_json). " \
-        "We recommend loading a different JSON library to improve performance."
-      )
-      true
-    end
-
-    :ok_json
+  class << self
+    # Returns the default adapter name (alias for default_adapter)
+    #
+    # @api public
+    # @deprecated Use {.default_adapter} instead
+    # @return [Symbol] the default adapter name
+    # @example
+    #   MultiJson.default_engine  #=> :oj
+    alias_method :default_engine, :default_adapter
   end
 
-  alias_method :default_engine, :default_adapter
-
-  # Get the current adapter class.
-  def adapter
-    return @adapter if defined?(@adapter) && @adapter
+  # @!endgroup
 
-    use nil # load default adapter
+  # @!group Adapter Management
 
-    @adapter
+  # Returns the current adapter class
+  #
+  # @api private
+  # @return [Class] the current adapter class
+  # @example
+  #   MultiJson.adapter  #=> MultiJson::Adapters::Oj
+  def adapter
+    @adapter ||= use(nil)
   end
+
+  # Returns the current adapter class (alias for adapter)
+  #
+  # @api private
+  # @deprecated Use {.adapter} instead
+  # @return [Class] the current adapter class
+  # @example
+  #   MultiJson.engine  #=> MultiJson::Adapters::Oj
   alias_method :engine, :adapter
 
-  # Set the JSON parser utilizing a symbol, string, or class.
-  # Supported by default are:
+  # Sets the adapter to use for JSON operations
   #
-  # * <tt>:oj</tt>
-  # * <tt>:json_gem</tt>
-  # * <tt>:json_pure</tt>
-  # * <tt>:ok_json</tt>
-  # * <tt>:yajl</tt>
-  # * <tt>:gson</tt> (JRuby only)
-  # * <tt>:jr_jackson</tt> (JRuby only)
+  # @api private
+  # @param new_adapter [Symbol, String, Module, nil] adapter specification
+  # @return [Class] the loaded adapter class
+  # @example
+  #   MultiJson.use(:oj)
   def use(new_adapter)
     @adapter = load_adapter(new_adapter)
   ensure
     OptionsCache.reset
   end
+
+  # Sets the adapter to use for JSON operations
+  #
+  # @api private
+  # @return [Class] the loaded adapter class
+  # @example
+  #   MultiJson.adapter = :json_gem
   alias_method :adapter=, :use
+
+  # Sets the adapter to use for JSON operations
+  #
+  # @api private
+  # @deprecated Use {.adapter=} instead
+  # @return [Class] the loaded adapter class
+  # @example
+  #   MultiJson.engine = :json_gem
   alias_method :engine=, :use
+  module_function :adapter=, :engine=
 
-  def load_adapter(new_adapter)
-    case new_adapter
-    when String, Symbol
-      load_adapter_from_string_name new_adapter.to_s
-    when NilClass, FalseClass
-      load_adapter default_adapter
-    when Class, Module
-      new_adapter
-    else
-      raise ::LoadError, new_adapter
-    end
-  rescue ::LoadError => e
-    raise(AdapterError.build(e), cause: e)
-  end
+  # @!endgroup
 
-  # Decode a JSON string into Ruby.
-  #
-  # <b>Options</b>
+  # @!group JSON Operations
+
+  # Parses a JSON string into a Ruby object
   #
-  # <tt>:symbolize_keys</tt> :: If true, will use symbols instead of strings for the keys.
-  # <tt>:adapter</tt> :: If set, the selected adapter will be used for this call.
+  # @api private
+  # @param string [String, #read] JSON string or IO-like object
+  # @param options [Hash] parsing options (adapter-specific)
+  # @return [Object] parsed Ruby object
+  # @raise [ParseError] if parsing fails
+  # @example
+  #   MultiJson.load('{"foo":"bar"}')  #=> {"foo" => "bar"}
   def load(string, options = {})
-    adapter = current_adapter(options)
-    begin
-      adapter.load(string, options)
-    rescue adapter::ParseError => e
-      raise(ParseError.build(e, string), cause: e)
-    end
+    adapter_class = current_adapter(options)
+    adapter_class.load(string, options)
+  rescue adapter_class::ParseError => e
+    raise ParseError.build(e, string)
   end
+
+  # Parses a JSON string into a Ruby object
+  #
+  # @api private
+  # @return [Object] parsed Ruby object
+  # @example
+  #   MultiJson.decode('{"foo":"bar"}')  #=> {"foo" => "bar"}
   alias_method :decode, :load
 
+  # Returns the adapter to use for the given options
+  #
+  # @api private
+  # @param options [Hash] options that may contain :adapter key
+  # @return [Class] adapter class
+  # @example
+  #   MultiJson.current_adapter(adapter: :oj)  #=> MultiJson::Adapters::Oj
   def current_adapter(options = {})
-    if (new_adapter = options[:adapter])
-      load_adapter(new_adapter)
-    else
-      adapter
-    end
+    options ||= {}
+    adapter_override = options[:adapter]
+    adapter_override ? load_adapter(adapter_override) : adapter
   end
 
-  # Encodes a Ruby object as JSON.
+  # Serializes a Ruby object to a JSON string
+  #
+  # @api private
+  # @param object [Object] object to serialize
+  # @param options [Hash] serialization options (adapter-specific)
+  # @return [String] JSON string
+  # @example
+  #   MultiJson.dump({foo: "bar"})  #=> '{"foo":"bar"}'
   def dump(object, options = {})
     current_adapter(options).dump(object, options)
   end
+
+  # Serializes a Ruby object to a JSON string
+  #
+  # @api private
+  # @return [String] JSON string
+  # @example
+  #   MultiJson.encode({foo: "bar"})  #=> '{"foo":"bar"}'
   alias_method :encode, :dump
 
-  #  Executes passed block using specified adapter.
+  # Executes a block using the specified adapter
+  #
+  # @api private
+  # @param new_adapter [Symbol, String, Module] adapter to use
+  # @yield block to execute with the temporary adapter
+  # @return [Object] result of the block
+  # @example
+  #   MultiJson.with_adapter(:json_gem) { MultiJson.dump({}) }
   def with_adapter(new_adapter)
-    old_adapter = adapter
+    previous_adapter = adapter
     self.adapter = new_adapter
     yield
   ensure
-    self.adapter = old_adapter
-  end
-  alias_method :with_engine, :with_adapter
-
-  private
-
-  # Checks for already loaded adapters and returns the first match
-  def loaded_adapter
-    return :oj if defined?(::Oj)
-    return :yajl if defined?(::Yajl)
-    return :jr_jackson if defined?(::JrJackson)
-    return :json_gem if defined?(::JSON::Ext::Parser)
-    return :gson if defined?(::Gson)
-
-    nil
+    self.adapter = previous_adapter
   end
 
-  # Attempts to load and return the first installable adapter
-  def installable_adapter
-    REQUIREMENT_MAP.each do |adapter, library|
-      require library
-      return adapter
-    rescue ::LoadError
-      next
-    end
-    nil
-  end
+  # Executes a block using the specified adapter
+  #
+  # @api private
+  # @deprecated Use {.with_adapter} instead
+  # @return [Object] result of the block
+  # @example
+  #   MultiJson.with_engine(:json_gem) { MultiJson.dump({}) }
+  alias_method :with_engine, :with_adapter
+  module_function :with_engine
 
-  def load_adapter_from_string_name(name)
-    normalized_name = ALIASES.fetch(name, name).to_s
-    require "multi_json/adapters/#{normalized_name.downcase}"
-    klass_name = normalized_name.split("_").map(&:capitalize).join
-    MultiJson::Adapters.const_get(klass_name)
-  end
+  # @!endgroup
 end