multi_json 1.15.0 → 1.21.1

data/lib/multi_json.rb

@@ -1,161 +1,320 @@
-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
 
-module MultiJson
-  include Options
-  extend self
-
-  def default_options=(value)
-    Kernel.warn "MultiJson.default_options setter is deprecated\n" \
-      'Use MultiJson.load_options and MultiJson.dump_options instead'
+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"
 
-    self.load_options = self.dump_options = value
-  end
+# 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=``, ``parse``, ``generate``,
+#    ``current_adapter``) so that both ``MultiJSON.parse(...)`` and legacy
+#    ``Class.new { include MultiJSON }.new.send(:parse, ...)`` 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``, ``load``,
+# ``dump``, etc.) lives in {file:lib/multi_json/deprecated.rb} so this
+# file stays focused on the current surface.
+#
+# @example Basic usage
+#   MultiJSON.parse('{"foo":"bar"}')  #=> {"foo" => "bar"}
+#   MultiJSON.generate({foo: "bar"})  #=> '{"foo":"bar"}'
+#
+# @example Specifying an adapter
+#   MultiJSON.use(:oj)
+#   MultiJSON.parse('{"foo":"bar"}', adapter: :json_gem)
+#
+# @api public
+module MultiJSON
+  extend Options
+  extend AdapterSelector
 
-  def default_options
-    Kernel.warn "MultiJson.default_options is deprecated\n" \
-      'Use MultiJson.load_options or 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
 
-    load_options
-  end
+  # 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.
+  # Public so the deprecated ``load_options`` / ``dump_options``
+  # aliases on the {Options} mixin can invoke it without routing
+  # through ``MultiJSON.send(...)``.
+  #
+  # The warning is tagged with the ``:deprecated`` category so callers
+  # can silence the whole set with ``Warning[:deprecated] = false`` or
+  # surface it via ``ruby -W:deprecated`` — the standard Ruby idiom for
+  # library deprecations since 2.7.
+  #
+  # @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.warn_deprecation_once(:foo, "MultiJSON.foo is deprecated")
+  def self.warn_deprecation_once(key, message)
+    Concurrency.synchronize(:deprecation_warnings) do
+      return if DEPRECATION_WARNINGS_SHOWN.include?(key)
 
-  %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."
+      Kernel.warn(message, category: :deprecated)
+      DEPRECATION_WARNINGS_SHOWN.add(key)
     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
-      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)
+  # ===========================================================================
+
+  # @!visibility private
+  module_function
 
-    use nil # load default adapter
+  # 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:
-  #
-  # * <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)
+
+  # Sets the adapter to use for JSON operations
+  #
+  # 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
   #
-  # <b>Options</b>
+  # @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
+  #
+  # 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.
-  def load(string, options = {})
-    adapter = current_adapter(options)
+  # @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.parse('{"foo":"bar"}')  #=> {"foo" => "bar"}
+  #   MultiJSON.parse("")               #=> nil
+  #   MultiJSON.parse("   \n")          #=> nil
+  def parse(string, 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.
-  def dump(object, options = {})
+  # 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.generate({foo: "bar"})  #=> '{"foo":"bar"}'
+  def generate(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=, :parse, :current_adapter, :generate
+
+  # ===========================================================================
+  # 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
+  # ===========================================================================
 
-  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)
+  private
+
+  # 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"
+
+# Backward-compatible alias for the legacy ``MultiJson`` constant name
+#
+# Downstream code that still writes ``MultiJson.parse(...)`` or
+# ``rescue MultiJson::ParseError`` continues to work, but emits a
+# one-time deprecation warning pointing at ``MultiJSON``. Each public
+# method on {MultiJSON} gets an explicit forwarder defined on this
+# module, and constant access resolves via {.const_missing}, so both
+# dotted calls and ``::`` constant lookups (including rescue clauses)
+# route through the canonical module.
+#
+# @api public
+# @deprecated Use {MultiJSON} (all-caps) instead. Will be removed in v2.0.
+module MultiJson
+  # Forward every public method MultiJSON exposes through an explicit
+  # singleton method on the legacy MultiJson module, so callers that
+  # capture the method as a Method object (``MultiJson.method(:load)``)
+  # find this forwarder instead of falling back to inherited methods like
+  # ``Kernel#load``. The earlier ``method_missing``-based shim left
+  # ``MultiJson.method(:load)`` resolving to ``Kernel#load`` (because
+  # ``Module#method`` doesn't consult ``method_missing``) and broke
+  # libraries (Sawyer, Octokit, Danger) that capture decoders as Method
+  # objects. Forwarding eagerly fixes the capture path while preserving
+  # the one-time deprecation warning each call emits.
+  (::MultiJSON.public_methods - ::Module.public_methods).each do |forwarded|
+    define_singleton_method(forwarded) do |*args, **kwargs, &block|
+      ::MultiJSON.warn_deprecation_once(:multi_json_constant,
+        "The MultiJson constant is deprecated and will be removed in v2.0. Use MultiJSON instead.")
+      ::MultiJSON.public_send(forwarded, *args, **kwargs, &block)
+    end
+  end
+
+  class << self
+    # Resolve missing constants to their {MultiJSON} counterparts
+    #
+    # Enables ``rescue MultiJson::ParseError`` and
+    # ``MultiJson::Adapters::Oj`` to keep working during the
+    # deprecation cycle.
+    #
+    # @api public
+    # @param name [Symbol] constant name
+    # @return [Object] the resolved constant from {MultiJSON}
+    # @example
+    #   MultiJson::ParseError  # returns MultiJSON::ParseError
+    def const_missing(name)
+      ::MultiJSON.warn_deprecation_once(:multi_json_constant,
+        "The MultiJson constant is deprecated and will be removed in v2.0. Use MultiJSON instead.")
+      ::MultiJSON.const_get(name)
+    end
   end
 end

metadata

@@ -1,90 +1,53 @@
 --- !ruby/object:Gem::Specification
 name: multi_json
 version: !ruby/object:Gem::Version
-  version: 1.15.0
+  version: 1.21.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: []
 files:
-- CHANGELOG.md
-- CONTRIBUTING.md
 - LICENSE.md
 - README.md
 - 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.21.1/CHANGELOG.md
+  documentation_uri: https://www.rubydoc.info/gems/multi_json/1.21.1
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/sferik/multi_json/tree/v1.21.1
+  wiki_uri: https://github.com/sferik/multi_json/wiki
 rdoc_options: []
 require_paths:
 - lib
@@ -92,15 +55,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.11
 specification_version: 4
 summary: A common interface to multiple JSON libraries.
 test_files: []