multi_json 1.15.0 → 1.20.1

data/lib/multi_json.rb

@@ -1,161 +1,268 @@
-require 'multi_json/options'
-require 'multi_json/version'
-require 'multi_json/adapter_error'
-require 'multi_json/parse_error'
-require 'multi_json/options_cache'
+# frozen_string_literal: true
 
+require_relative "multi_json/concurrency"
+require_relative "multi_json/options"
+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.
+#
+# ## Method-definition patterns
+#
+# The current public API uses two patterns, each chosen for a specific reason:
+#
+# 1. ``module_function`` creates both a class method and a private instance
+#    method from a single ``def``. This is used for the hot-path API
+#    (``adapter``, ``use``, ``adapter=``, ``load``, ``dump``,
+#    ``current_adapter``) so that both ``MultiJson.load(...)`` and legacy
+#    ``Class.new { include MultiJson }.new.send(:load, ...)`` invocations
+#    work through the same body. The instance versions are re-publicized
+#    below so YARD renders them as part of the public API.
+# 2. ``def self.foo`` creates only a singleton method, giving mutation
+#    testing a single canonical definition to target. This is used for
+#    {.with_adapter}, which needs precise mutation coverage of its
+#    fiber-local save/restore logic.
+#
+# Deprecated public API (``decode``, ``encode``, ``engine``, etc.) lives in
+# {file:lib/multi_json/deprecated.rb} so this file stays focused on the
+# current surface.
+#
+# @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\n" \
-      'Use MultiJson.load_options and MultiJson.dump_options instead'
+  # Tracks which deprecation warnings have already been emitted so each one
+  # fires at most once per process. Stored as a Set rather than a Hash so
+  # presence checks have unambiguous semantics for mutation tests.
+  DEPRECATION_WARNINGS_SHOWN = Set.new
+  private_constant :DEPRECATION_WARNINGS_SHOWN
 
-    self.load_options = self.dump_options = value
-  end
+  class << self
+    private
 
-  def default_options
-    Kernel.warn "MultiJson.default_options is deprecated\n" \
-      'Use MultiJson.load_options or MultiJson.dump_options instead'
+    # Emit a deprecation warning at most once per process for the given key
+    #
+    # Defined as a singleton method (rather than via module_function) so
+    # there is exactly one definition for mutation tests to target. The
+    # deprecated method bodies invoke this via ``warn_deprecation_once(...)``
+    # (singleton callers) and via the private instance delegates routing
+    # through the singleton for legacy ``include MultiJson`` consumers.
+    #
+    # @api private
+    # @param key [Symbol] identifier for the deprecation (typically the method name)
+    # @param message [String] warning message to emit on first call
+    # @return [void]
+    # @example
+    #   MultiJson.send(:warn_deprecation_once, :foo, "MultiJson.foo is deprecated")
+    def warn_deprecation_once(key, message)
+      Concurrency.synchronize(:deprecation_warnings) do
+        return if DEPRECATION_WARNINGS_SHOWN.include?(key)
 
-    load_options
-  end
-
-  %w(cached_options reset_cached_options!).each do |method_name|
-    define_method method_name do |*|
-      Kernel.warn "MultiJson.#{method_name} method is deprecated and no longer used."
-    end
-  end
-
-  ALIASES = {'jrjackson' => 'jr_jackson'}
-
-  REQUIREMENT_MAP = [
-    [:oj,         'oj'],
-    [:yajl,       'yajl'],
-    [:jr_jackson, 'jrjackson'],
-    [:json_gem,   'json/ext'],
-    [:gson,       'gson'],
-    [:json_pure,  'json/pure'],
-  ]
-
-  # The default adapter based on what you currently
-  # have loaded and installed. First checks to see
-  # if any adapters are already loaded, then checks
-  # to see which are installed if none are loaded.
-  def default_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)
-
-    REQUIREMENT_MAP.each do |adapter, library|
-      begin
-        require library
-        return adapter
-      rescue ::LoadError
-        next
+        Kernel.warn(message)
+        DEPRECATION_WARNINGS_SHOWN.add(key)
       end
     end
+  end
 
-    Kernel.warn '[WARNING] MultiJson is using the default adapter (ok_json). ' \
-      'We recommend loading a different JSON library to improve performance.'
+  # Resolve the ``ParseError`` constant for an adapter class
+  #
+  # The result is memoized on the adapter class itself in a
+  # ``@_multi_json_parse_error`` ivar so subsequent ``MultiJson.load``
+  # calls skip the constant lookup entirely. The lookup is performed
+  # with ``inherit: false`` so a stray top-level ``::ParseError``
+  # constant in the host process is correctly ignored on every
+  # supported Ruby implementation — TruffleRuby's ``::`` operator
+  # walks the ancestor chain and would otherwise pick up the top-level
+  # constant. Custom adapters that don't define their own
+  # ``ParseError`` get a clear {AdapterError} instead of the bare
+  # ``NameError`` Ruby would raise from the rescue clause.
+  #
+  # @api private
+  # @param adapter_class [Class] adapter class to inspect
+  # @return [Class] the adapter's ParseError class
+  # @raise [AdapterError] when the adapter doesn't define ParseError
+  def self.parse_error_class_for(adapter_class)
+    cached = adapter_class.instance_variable_get(:@_multi_json_parse_error)
+    return cached if cached
 
-    :ok_json
+    resolved = adapter_class.const_get(:ParseError, false)
+    adapter_class.instance_variable_set(:@_multi_json_parse_error, resolved)
+  rescue NameError
+    raise AdapterError, "Adapter #{adapter_class} must define a ParseError constant"
   end
-  alias_method :default_engine, :default_adapter
 
-  # Get the current adapter class.
-  def adapter
-    return @adapter if defined?(@adapter) && @adapter
+  # ===========================================================================
+  # Public API (module_function: class + private instance method)
+  # ===========================================================================
 
-    use nil # load default adapter
+  # @!visibility private
+  module_function
+
+  # Returns the current adapter class
+  #
+  # Honors a fiber-local override set by {.with_adapter} so concurrent
+  # blocks observe their own adapter without clobbering the process-wide
+  # default. Falls back to the process default when no override is set.
+  #
+  # @api public
+  # @return [Class] the current adapter class
+  # @example
+  #   MultiJson.adapter  #=> MultiJson::Adapters::Oj
+  def adapter
+    override = Fiber[:multi_json_adapter]
+    return override if override
 
-    @adapter
+    @adapter ||= use(nil)
   end
-  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>:nsjsonserialization</tt> (MacRuby only)
-  # * <tt>:gson</tt> (JRuby only)
-  # * <tt>:jr_jackson</tt> (JRuby only)
+  # The merged-options cache is only reset when the new adapter loads
+  # successfully. A failed ``use(:nonexistent)`` leaves the cache in
+  # place so the previously-active adapter keeps its cached entries.
+  #
+  # @api public
+  # @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
-  alias_method :adapter=, :use
-  alias_method :engine=, :use
-
-  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
-      fail ::LoadError, new_adapter
+    loaded = load_adapter(new_adapter)
+    Concurrency.synchronize(:adapter) do
+      OptionsCache.reset
+      @adapter = loaded
     end
-  rescue ::LoadError => exception
-    raise AdapterError.build(exception)
   end
 
-  # Decode a JSON string into Ruby.
+  # Sets the adapter to use for JSON operations
+  #
+  # @api public
+  # @return [Class] the loaded adapter class
+  # @example
+  #   MultiJson.adapter = :json_gem
+  alias_method :adapter=, :use
+  module_function :adapter=
+
+  # Parses a JSON string into a Ruby object
   #
-  # <b>Options</b>
+  # Returns ``nil`` for ``nil``, empty, and whitespace-only inputs
+  # instead of raising. Pass an explicit non-blank string if you want
+  # to surface a {ParseError} for empty payloads at the call site.
   #
-  # <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 public
+  # @param string [String, #read] JSON string or IO-like object
+  # @param options [Hash] parsing options (adapter-specific)
+  # @return [Object, nil] parsed Ruby object, or nil for blank input
+  # @raise [ParseError] if parsing fails
+  # @raise [AdapterError] if the adapter doesn't define a ``ParseError`` constant
+  # @example
+  #   MultiJson.load('{"foo":"bar"}')  #=> {"foo" => "bar"}
+  #   MultiJson.load("")               #=> nil
+  #   MultiJson.load("   \n")          #=> nil
   def load(string, options = {})
-    adapter = current_adapter(options)
+    adapter_class = current_adapter(options)
+    parse_error_class = MultiJson.parse_error_class_for(adapter_class)
     begin
-      adapter.load(string, options)
-    rescue adapter::ParseError => exception
-      raise ParseError.build(exception, string)
+      adapter_class.load(string, options)
+    rescue parse_error_class => e
+      raise ParseError.build(e, string)
     end
   end
-  alias_method :decode, :load
 
+  # Returns the adapter to use for the given options
+  #
+  # ``nil`` is accepted as a no-options sentinel — explicit
+  # ``current_adapter(nil)`` calls fall through to the process default
+  # adapter without raising.
+  #
+  # @api public
+  # @param options [Hash, nil] options that may contain :adapter key, or
+  #   nil to use the process default
+  # @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 ||= Options::EMPTY_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 public
+  # @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
-  alias_method :encode, :dump
 
-  #  Executes passed block using specified adapter.
-  def with_adapter(new_adapter)
-    old_adapter = adapter
-    self.adapter = new_adapter
+  # Re-publicize the instance versions of the module_function methods so
+  # YARD/yardstick render them as part of the public API and legacy
+  # ``include MultiJson`` consumers can call them without ``.send``.
+  public :adapter, :use, :adapter=, :load, :current_adapter, :dump
+
+  # ===========================================================================
+  # Public API (def self.foo: singleton-only, for mutation-test precision)
+  # ===========================================================================
+
+  # Executes a block using the specified adapter
+  #
+  # Defined as a singleton method so mutation testing has exactly one
+  # definition to target. The override is stored in fiber-local storage
+  # so concurrent fibers and threads each see their own adapter without
+  # racing on a shared module variable; nested calls save and restore
+  # the previous fiber-local value.
+  #
+  # @api public
+  # @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 self.with_adapter(new_adapter)
+    previous_override = Fiber[:multi_json_adapter]
+    Fiber[:multi_json_adapter] = load_adapter(new_adapter)
     yield
   ensure
-    self.adapter = old_adapter
+    Fiber[:multi_json_adapter] = previous_override
   end
-  alias_method :with_engine, :with_adapter
 
-private
+  # ===========================================================================
+  # Private instance-method delegates for the singleton-only methods above
+  # ===========================================================================
+
+  private
 
-  def load_adapter_from_string_name(name)
-    name = ALIASES.fetch(name, name)
-    require "multi_json/adapters/#{name.downcase}"
-    klass_name = name.to_s.split('_').map(&:capitalize) * ''
-    MultiJson::Adapters.const_get(klass_name)
+  # Instance-method delegate for {MultiJson.with_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
+  #   class Foo; include MultiJson; end
+  #   Foo.new.send(:with_adapter, :json_gem) { ... }
+  def with_adapter(new_adapter, &)
+    MultiJson.with_adapter(new_adapter, &)
   end
 end
+
+require_relative "multi_json/deprecated"

metadata

@@ -1,54 +1,21 @@
 --- !ruby/object:Gem::Specification
 name: multi_json
 version: !ruby/object:Gem::Version
-  version: 1.15.0
+  version: 1.20.1
 platform: ruby
 authors:
 - Michael Bleigh
 - Josh Kalderimis
-- Erik Michaels-Ober
+- Erik Berlin
 - Pavel Pravosud
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-07-10 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '10.5'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '10.5'
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.9'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.9'
-description: A common interface to multiple JSON libraries, including Oj, Yajl, the
-  JSON gem (with C-extensions), the pure-Ruby JSON gem, NSJSONSerialization, gson.rb,
-  JrJackson, and OkJson.
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: A common interface to multiple JSON libraries, including fast_jsonparser,
+  Oj, Yajl, and the JSON gem.
 email:
-- michael@intridea.com
-- josh.kalderimis@gmail.com
 - sferik@gmail.com
-- pavel@pravosud.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -60,31 +27,29 @@ files:
 - lib/multi_json.rb
 - lib/multi_json/adapter.rb
 - lib/multi_json/adapter_error.rb
-- lib/multi_json/adapters/gson.rb
-- lib/multi_json/adapters/jr_jackson.rb
-- lib/multi_json/adapters/json_common.rb
+- lib/multi_json/adapter_selector.rb
+- lib/multi_json/adapters/fast_jsonparser.rb
 - lib/multi_json/adapters/json_gem.rb
-- lib/multi_json/adapters/json_pure.rb
-- lib/multi_json/adapters/nsjsonserialization.rb
 - lib/multi_json/adapters/oj.rb
-- lib/multi_json/adapters/ok_json.rb
+- lib/multi_json/adapters/oj_common.rb
 - lib/multi_json/adapters/yajl.rb
-- lib/multi_json/convertible_hash_keys.rb
+- lib/multi_json/concurrency.rb
+- lib/multi_json/deprecated.rb
 - lib/multi_json/options.rb
 - lib/multi_json/options_cache.rb
+- lib/multi_json/options_cache/mutex_store.rb
 - lib/multi_json/parse_error.rb
-- lib/multi_json/vendor/okjson.rb
 - lib/multi_json/version.rb
-homepage: https://github.com/intridea/multi_json
+homepage: https://github.com/sferik/multi_json
 licenses:
 - MIT
 metadata:
-  bug_tracker_uri: https://github.com/intridea/multi_json/issues
-  changelog_uri: https://github.com/intridea/multi_json/blob/v1.15.0/CHANGELOG.md
-  documentation_uri: https://www.rubydoc.info/gems/multi_json/1.15.0
-  source_code_uri: https://github.com/intridea/multi_json/tree/v1.15.0
-  wiki_uri: https://github.com/intridea/multi_json/wiki
-post_install_message: 
+  bug_tracker_uri: https://github.com/sferik/multi_json/issues
+  changelog_uri: https://github.com/sferik/multi_json/blob/v1.20.1/CHANGELOG.md
+  documentation_uri: https://www.rubydoc.info/gems/multi_json/1.20.1
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/sferik/multi_json/tree/v1.20.1
+  wiki_uri: https://github.com/sferik/multi_json/wiki
 rdoc_options: []
 require_paths:
 - lib
@@ -92,15 +57,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.5
+      version: '0'
 requirements: []
-rubygems_version: 3.0.3
-signing_key: 
+rubygems_version: 4.0.10
 specification_version: 4
 summary: A common interface to multiple JSON libraries.
 test_files: []

data/lib/multi_json/adapters/gson.rb

@@ -1,20 +0,0 @@
-require 'gson'
-require 'stringio'
-require 'multi_json/adapter'
-
-module MultiJson
-  module Adapters
-    # Use the gson.rb library to dump/load.
-    class Gson < Adapter
-      ParseError = ::Gson::DecodeError
-
-      def load(string, options = {})
-        ::Gson::Decoder.new(options).decode(string)
-      end
-
-      def dump(object, options = {})
-        ::Gson::Encoder.new(options).encode(object)
-      end
-    end
-  end
-end

data/lib/multi_json/adapters/jr_jackson.rb

@@ -1,25 +0,0 @@
-require 'jrjackson' unless defined?(::JrJackson)
-require 'multi_json/adapter'
-
-module MultiJson
-  module Adapters
-    # Use the jrjackson.rb library to dump/load.
-    class JrJackson < Adapter
-      ParseError = ::JrJackson::ParseError
-
-      def load(string, options = {}) #:nodoc:
-        ::JrJackson::Json.load(string, options)
-      end
-
-      if ::JrJackson::Json.method(:dump).arity == 1
-        def dump(object, _)
-          ::JrJackson::Json.dump(object)
-        end
-      else
-        def dump(object, options = {})
-          ::JrJackson::Json.dump(object, options)
-        end
-      end
-    end
-  end
-end

data/lib/multi_json/adapters/json_common.rb

@@ -1,23 +0,0 @@
-require 'multi_json/adapter'
-
-module MultiJson
-  module Adapters
-    class JsonCommon < Adapter
-      defaults :load, :create_additions => false, :quirks_mode => true
-
-      def load(string, options = {})
-        if string.respond_to?(:force_encoding)
-          string = string.dup.force_encoding(::Encoding::ASCII_8BIT)
-        end
-
-        options[:symbolize_names] = true if options.delete(:symbolize_keys)
-        ::JSON.parse(string, options)
-      end
-
-      def dump(object, options = {})
-        options.merge!(::JSON::PRETTY_STATE_PROTOTYPE.to_h) if options.delete(:pretty)
-        object.to_json(options)
-      end
-    end
-  end
-end

data/lib/multi_json/adapters/json_pure.rb

@@ -1,11 +0,0 @@
-require 'json/pure'
-require 'multi_json/adapters/json_common'
-
-module MultiJson
-  module Adapters
-    # Use JSON pure to dump/load.
-    class JsonPure < JsonCommon
-      ParseError = ::JSON::ParserError
-    end
-  end
-end

data/lib/multi_json/adapters/nsjsonserialization.rb

@@ -1,35 +0,0 @@
-# This adapter is here for legacy reasons. We can't really test it, so it's hard
-# to tell if it's even working properly. If you're still using it, please
-# consider migrating to any other adapter out there.
-framework 'Foundation'
-require 'multi_json/adapters/ok_json'
-
-module MultiJson
-  module Adapters
-    class Nsjsonserialization < MultiJson::Adapters::OkJson
-      ParseError = ::MultiJson::OkJson::Error
-
-      def load(string, options = {})
-        data = string.dataUsingEncoding(NSUTF8StringEncoding)
-        object = NSJSONSerialization.JSONObjectWithData(data, :options => NSJSONReadingMutableContainers | NSJSONReadingMutableLeaves, :error => nil)
-        if object
-          object = symbolize_keys(object) if options[:symbolize_keys]
-          object
-        else
-          super(string, options)
-        end
-      end
-
-      def dump(object, options = {})
-        pretty = options[:pretty] ? NSJSONWritingPrettyPrinted : 0
-        object = object.as_json if object.respond_to?(:as_json)
-        if NSJSONSerialization.isValidJSONObject(object)
-          data = NSJSONSerialization.dataWithJSONObject(object, :options => pretty, :error => nil)
-          NSMutableString.alloc.initWithData(data, :encoding => NSUTF8StringEncoding)
-        else
-          super(object, options)
-        end
-      end
-    end
-  end
-end

data/lib/multi_json/adapters/ok_json.rb

@@ -1,23 +0,0 @@
-require 'multi_json/adapter'
-require 'multi_json/convertible_hash_keys'
-require 'multi_json/vendor/okjson'
-
-module MultiJson
-  module Adapters
-    class OkJson < Adapter
-      include ConvertibleHashKeys
-      ParseError = ::MultiJson::OkJson::Error
-
-      def load(string, options = {})
-        result = ::MultiJson::OkJson.decode("[#{string}]").first
-        options[:symbolize_keys] ? symbolize_keys(result) : result
-      rescue ArgumentError # invalid byte sequence in UTF-8
-        raise ParseError
-      end
-
-      def dump(object, _ = {})
-        ::MultiJson::OkJson.valenc(stringify_keys(object))
-      end
-    end
-  end
-end