multi_json 1.19.1 → 1.21.1

data/lib/multi_json.rb

@@ -1,3 +1,6 @@
+# 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"
@@ -7,229 +10,311 @@ require_relative "multi_json/adapter_selector"
 
 # A unified interface for JSON libraries in Ruby
 #
-# MultiJson allows swapping between JSON backends without changing your code.
+# 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.load('{"foo":"bar"}')  #=> {"foo" => "bar"}
-#   MultiJson.dump({foo: "bar"})     #=> '{"foo":"bar"}'
+#   MultiJSON.parse('{"foo":"bar"}')  #=> {"foo" => "bar"}
+#   MultiJSON.generate({foo: "bar"})  #=> '{"foo":"bar"}'
 #
 # @example Specifying an adapter
-#   MultiJson.use(:oj)
-#   MultiJson.load('{"foo":"bar"}', adapter: :json_gem)
+#   MultiJSON.use(:oj)
+#   MultiJSON.parse('{"foo":"bar"}', adapter: :json_gem)
 #
 # @api public
-module MultiJson
+module MultiJSON
   extend Options
   extend AdapterSelector
 
-  # @!visibility private
-  module_function
-
-  # @!group Configuration
+  # 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
 
-  # Set default options for both load and dump operations
+  # Emit a deprecation warning at most once per process for the given key
   #
-  # @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
+  # 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
-  # @deprecated Use {.load_options} or {.dump_options} instead
-  # @return [Hash] the current load options
+  # @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.default_options  #=> {}
-  def default_options
-    Kernel.warn "MultiJson.default_options is deprecated\n" \
-                "Use MultiJson.load_options or MultiJson.dump_options instead"
-    load_options
-  end
+  #   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)
 
-  # @deprecated These methods are no longer used
-  %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
 
-  # 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"
-  }.freeze
+  # 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
 
-  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
+    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
 
-  # @!endgroup
+  # ===========================================================================
+  # Public API (module_function: class + private instance method)
+  # ===========================================================================
 
-  # @!group Adapter Management
+  # @!visibility private
+  module_function
 
   # Returns the current adapter class
   #
-  # @api private
+  # 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
+  #   MultiJSON.adapter  #=> MultiJSON::Adapters::Oj
   def adapter
+    override = Fiber[:multi_json_adapter]
+    return override if override
+
     @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
-
   # Sets the adapter to use for JSON operations
   #
-  # @api private
+  # 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)
+  #   MultiJSON.use(:oj)
   def use(new_adapter)
-    @adapter = load_adapter(new_adapter)
-  ensure
-    OptionsCache.reset
+    loaded = load_adapter(new_adapter)
+    Concurrency.synchronize(:adapter) do
+      OptionsCache.reset
+      @adapter = loaded
+    end
   end
 
   # Sets the adapter to use for JSON operations
   #
-  # @api private
+  # @api public
   # @return [Class] the loaded adapter class
   # @example
-  #   MultiJson.adapter = :json_gem
+  #   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=
-
-  # @!endgroup
-
-  # @!group JSON Operations
+  module_function :adapter=
 
   # Parses a JSON string into a Ruby object
   #
-  # @api private
+  # 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.
+  #
+  # @api public
   # @param string [String, #read] JSON string or IO-like object
   # @param options [Hash] parsing options (adapter-specific)
-  # @return [Object] parsed Ruby object
+  # @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"}
-  def load(string, options = {})
+  #   MultiJSON.parse('{"foo":"bar"}')  #=> {"foo" => "bar"}
+  #   MultiJSON.parse("")               #=> nil
+  #   MultiJSON.parse("   \n")          #=> nil
+  def parse(string, options = {})
     adapter_class = current_adapter(options)
-    adapter_class.load(string, options)
-  rescue adapter_class::ParseError => e
-    raise ParseError.build(e, string)
+    parse_error_class = MultiJSON.parse_error_class_for(adapter_class)
+    begin
+      adapter_class.load(string, options)
+    rescue parse_error_class => e
+      raise ParseError.build(e, string)
+    end
   end
 
-  # Parses a JSON string into a Ruby object
-  #
-  # @api private
-  # @deprecated Use {.load} instead
-  # @return [Object] parsed Ruby object
-  # @example
-  #   MultiJson.decode('{"foo":"bar"}')  #=> {"foo" => "bar"}
-  alias_method :decode, :load
-  module_function :decode
-
   # Returns the adapter to use for the given options
   #
-  # @api private
-  # @param options [Hash] options that may contain :adapter key
+  # ``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
+  #   MultiJSON.current_adapter(adapter: :oj)  #=> MultiJSON::Adapters::Oj
   def current_adapter(options = {})
-    options ||= {}
+    options ||= Options::EMPTY_OPTIONS
     adapter_override = options[:adapter]
     adapter_override ? load_adapter(adapter_override) : adapter
   end
 
   # Serializes a Ruby object to a JSON string
   #
-  # @api private
+  # @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 = {})
+  #   MultiJSON.generate({foo: "bar"})  #=> '{"foo":"bar"}'
+  def generate(object, options = {})
     current_adapter(options).dump(object, options)
   end
 
-  # Serializes a Ruby object to a JSON string
-  #
-  # @api private
-  # @deprecated Use {.dump} instead
-  # @return [String] JSON string
-  # @example
-  #   MultiJson.encode({foo: "bar"})  #=> '{"foo":"bar"}'
-  alias_method :encode, :dump
-  module_function :encode
+  # 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
   #
-  # @api private
+  # 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 with_adapter(new_adapter)
-    previous_adapter = adapter
-    self.adapter = new_adapter
+  #   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 = previous_adapter
+    Fiber[:multi_json_adapter] = previous_override
   end
 
-  # Executes a block using the specified adapter
+  # ===========================================================================
+  # Private instance-method delegates for the singleton-only methods above
+  # ===========================================================================
+
+  private
+
+  # Instance-method delegate for {MultiJSON.with_adapter}
   #
   # @api private
-  # @deprecated Use {.with_adapter} instead
+  # @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_engine(:json_gem) { MultiJson.dump({}) }
-  alias_method :with_engine, :with_adapter
-  module_function :with_engine
+  #   class Foo; include MultiJSON; end
+  #   Foo.new.send(:with_adapter, :json_gem) { ... }
+  def with_adapter(new_adapter, &)
+    MultiJSON.with_adapter(new_adapter, &)
+  end
+end
 
-  # @!endgroup
+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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: multi_json
 version: !ruby/object:Gem::Version
-  version: 1.19.1
+  version: 1.21.1
 platform: ruby
 authors:
 - Michael Bleigh
@@ -13,15 +13,13 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: A common interface to multiple JSON libraries, including fast_jsonparser,
-  Oj, Yajl, the JSON gem (with C-extensions), gson, JrJackson, and OkJson.
+  Oj, Yajl, and the JSON gem.
 email:
 - sferik@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- CHANGELOG.md
-- CONTRIBUTING.md
 - LICENSE.md
 - README.md
 - lib/multi_json.rb
@@ -29,28 +27,26 @@ files:
 - lib/multi_json/adapter_error.rb
 - lib/multi_json/adapter_selector.rb
 - lib/multi_json/adapters/fast_jsonparser.rb
-- lib/multi_json/adapters/gson.rb
-- lib/multi_json/adapters/jr_jackson.rb
 - lib/multi_json/adapters/json_gem.rb
 - lib/multi_json/adapters/oj.rb
 - lib/multi_json/adapters/oj_common.rb
-- lib/multi_json/adapters/ok_json.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/sferik/multi_json
 licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/sferik/multi_json/issues
-  changelog_uri: https://github.com/sferik/multi_json/blob/v1.19.1/CHANGELOG.md
-  documentation_uri: https://www.rubydoc.info/gems/multi_json/1.19.1
+  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.19.1
+  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:
@@ -59,14 +55,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.11
 specification_version: 4
 summary: A common interface to multiple JSON libraries.
 test_files: []