multi_json 1.19.1 → 1.20.0

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"
@@ -10,6 +13,26 @@ require_relative "multi_json/adapter_selector"
 # 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"}'
@@ -23,169 +46,165 @@ 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
-  #
-  # @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
+  class << self
+    private
 
-  # 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\n" \
-                "Use MultiJson.load_options or MultiJson.dump_options instead"
-    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. 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)
 
-  # @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)
+        DEPRECATION_WARNINGS_SHOWN.add(key)
+      end
     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
   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)
   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
   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"}
+  #   MultiJson.load("")               #=> nil
+  #   MultiJson.load("   \n")          #=> nil
   def load(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
   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
@@ -195,41 +214,55 @@ module MultiJson
     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=, :load, :current_adapter, :dump
+
+  # ===========================================================================
+  # 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
+  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
-
-  # @!endgroup
+  #   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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: multi_json
 version: !ruby/object:Gem::Version
-  version: 1.19.1
+  version: 1.20.0
 platform: ruby
 authors:
 - Michael Bleigh
@@ -13,7 +13,7 @@ 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: []
@@ -29,28 +29,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.20.0/CHANGELOG.md
+  documentation_uri: https://www.rubydoc.info/gems/multi_json/1.20.0
   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.20.0
   wiki_uri: https://github.com/sferik/multi_json/wiki
 rdoc_options: []
 require_paths:
@@ -59,14 +57,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.10
 specification_version: 4
 summary: A common interface to multiple JSON libraries.
 test_files: []

data/lib/multi_json/adapters/gson.rb

@@ -1,37 +0,0 @@
-require "gson"
-require_relative "../adapter"
-
-module MultiJson
-  module Adapters
-    # Use the gson.rb library to dump/load.
-    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
-    end
-  end
-end

data/lib/multi_json/adapters/jr_jackson.rb

@@ -1,52 +0,0 @@
-require "jrjackson" unless defined?(JrJackson)
-require_relative "../adapter"
-
-module MultiJson
-  module Adapters
-    # Use the jrjackson.rb library to dump/load.
-    class JrJackson < Adapter
-      ParseError = ::JrJackson::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 = {})
-        ::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
-      end
-    end
-  end
-end

data/lib/multi_json/adapters/ok_json.rb

@@ -1,43 +0,0 @@
-require_relative "../adapter"
-require_relative "../convertible_hash_keys"
-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
-      rescue ArgumentError # invalid byte sequence in UTF-8
-        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
-    end
-  end
-end

data/lib/multi_json/convertible_hash_keys.rb

@@ -1,66 +0,0 @@
-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
-
-    # 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
-
-    # 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
-
-    # 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 Hash
-        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
-        convert_simple_object(value)
-      end
-    end
-
-    # 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
-
-    # 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
-  end
-end