multi_json 1.15.0 → 1.20.1

data/CONTRIBUTING.md

@@ -10,36 +10,43 @@ Here are some ways *you* can contribute:
 * by reporting bugs
 * by suggesting new features
 * by writing or editing documentation
-* by writing specifications
+* by writing tests
 * by writing code (**no patch is too small**: fix typos, add comments, clean up
   inconsistent whitespace)
 * by refactoring code
 * by closing [issues][]
 * by reviewing patches
 
-[issues]: https://github.com/intridea/multi_json/issues
+[issues]: https://github.com/sferik/multi_json/issues
 
 ## Submitting an Issue
 We use the [GitHub issue tracker][issues] to track bugs and features. Before
 submitting a bug report or feature request, check to make sure it hasn't
-already been submitted. When submitting a bug report, please include a [Gist][]
-that includes a stack trace and any details that may be necessary to reproduce
-the bug, including your gem version, Ruby version, and operating system.
-Ideally, a bug report should include a pull request with failing specs.
+already been submitted. When submitting a bug report, please include a
+[Gist][gist] that includes a stack trace and any details that may be necessary
+to reproduce the bug, including your gem version, Ruby version, and operating
+system. Ideally, a bug report should include a pull request with failing tests.
 
 [gist]: https://gist.github.com/
 
 ## Submitting a Pull Request
-1. [Fork the repository.][fork]
-2. [Create a topic branch.][branch]
-3. Add specs for your unimplemented feature or bug fix.
-4. Run `bundle exec rake spec`. If your specs pass, return to step 3.
-5. Implement your feature or bug fix.
-6. Run `bundle exec rake spec`. If your specs fail, return to step 5.
-7. Run `open coverage/index.html`. If your changes are not completely covered
-   by your tests, return to step 3.
-8. Add, commit, and push your changes.
-9. [Submit a pull request.][pr]
+1.  [Fork the repository.][fork]
+2.  [Create a topic branch.][branch]
+3.  Add tests for your unimplemented feature or bug fix.
+4.  Run `bundle exec rake test`. If your tests pass, return to step 3.
+5.  Implement your feature or bug fix.
+6.  Run `bundle exec rake test`. If your tests fail, return to step 5.
+7.  Run `open coverage/index.html`. If your changes are not completely covered
+    by your tests, return to step 3.
+8.  Run `bundle exec rake mutant` and kill any surviving mutants.
+9.  Run `bundle exec rake lint` and fix any offenses.
+10. Run `bundle exec rake yardstick` and add any missing documentation.
+11. Run `bundle exec rake steep` and ensure that the code typechecks.
+12. Add, commit, and push your changes.
+13. [Submit a pull request][pr] that summarizes *what* changes you made and
+    *why* you made them. If you made any significant decisions along the way,
+    describe the options you considered and how you thought about the
+    tradeoffs.
 
 [fork]: http://help.github.com/fork-a-repo/
 [branch]: http://learn.github.com/p/branching.html

data/LICENSE.md

@@ -1,4 +1,4 @@
-Copyright (c) 2010-2013 Michael Bleigh, Josh Kalderimis, Erik Michaels-Ober, Pavel Pravosud
+Copyright (c) 2010-2026 Erik Berlin, Michael Bleigh, Josh Kalderimis, Pavel Pravosud
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,8 +1,12 @@
 # MultiJSON
 
-[![Gem Version](http://img.shields.io/gem/v/multi_json.svg)][gem]
-[![Build Status](http://travis-ci.org/intridea/multi_json.svg)][travis]
-[![Code Climate](https://codeclimate.com/github/intridea/multi_json.svg)][codeclimate]
+[![Tests](https://github.com/sferik/multi_json/actions/workflows/tests.yml/badge.svg)][tests]
+[![Linter](https://github.com/sferik/multi_json/actions/workflows/linter.yml/badge.svg)][linter]
+[![Mutant](https://github.com/sferik/multi_json/actions/workflows/mutant.yml/badge.svg)][mutant]
+[![Typecheck](https://github.com/sferik/multi_json/actions/workflows/typecheck.yml/badge.svg)][typecheck]
+[![Docs](https://github.com/sferik/multi_json/actions/workflows/docs.yml/badge.svg)][docs]
+[![Maintainability](https://qlty.sh/badges/fde3f4a8-c331-44be-b1e6-45842137def9/maintainability.svg)][qlty]
+[![Gem Version](https://badge.fury.io/rb/multi_json.svg)][gem]
 
 Lots of Ruby libraries parse JSON and everyone has their favorite JSON coder.
 Instead of choosing a single JSON coder and forcing users of your library to be
@@ -10,27 +14,54 @@ stuck with it, you can use MultiJSON instead, which will simply choose the
 fastest available JSON coder. Here's how to use it:
 
 ```ruby
-require 'multi_json'
+require "multi_json"
 
-MultiJson.load('{"abc":"def"}') #=> {"abc" => "def"}
-MultiJson.load('{"abc":"def"}', :symbolize_keys => true) #=> {:abc => "def"}
-MultiJson.dump({:abc => 'def'}) # convert Ruby back to JSON
-MultiJson.dump({:abc => 'def'}, :pretty => true) # encoded in a pretty form (if supported by the coder)
+MultiJson.load('{"abc":"def"}')                       #=> {"abc" => "def"}
+MultiJson.load('{"abc":"def"}', symbolize_keys: true) #=> {abc: "def"}
+MultiJson.dump({abc: "def"})                          # convert Ruby back to JSON
+MultiJson.dump({abc: "def"}, pretty: true)            # encoded in a pretty form (if supported by the coder)
 ```
 
-When loading invalid JSON, MultiJSON will throw a `MultiJson::ParseError`. `MultiJson::DecodeError` and `MultiJson::LoadError` are aliases for backwards compatibility.
+`MultiJson.load` returns `nil` for `nil`, empty, and whitespace-only inputs
+instead of raising, so a missing or blank payload is observable as a `nil`
+return value rather than an exception. When loading invalid JSON, MultiJSON
+will throw a `MultiJson::ParseError`. `MultiJson::DecodeError` and
+`MultiJson::LoadError` are aliases for backwards compatibility.
 
 ```ruby
 begin
-  MultiJson.load('{invalid json}')
+  MultiJson.load("{invalid json}")
 rescue MultiJson::ParseError => exception
-  exception.data # => "{invalid json}"
-  exception.cause # => JSON::ParserError: 795: unexpected token at '{invalid json}'
+  exception.data    #=> "{invalid json}"
+  exception.cause   #=> JSON::ParserError: ...
+  exception.line    #=> 1 (for adapters that report a location, e.g. Oj or the json gem)
+  exception.column  #=> 2
 end
 ```
 
 `ParseError` instance has `cause` reader which contains the original exception.
-It also has `data` reader with the input that caused the problem.
+It also has `data` reader with the input that caused the problem, and `line`/`column`
+readers populated for adapters whose error messages include a location (Oj and the
+json gem). Adapters that don't include one (Yajl, fast_jsonparser) leave both nil.
+
+### Tuning the options cache
+
+MultiJSON memoizes the merged option hash for each `load`/`dump` call so identical
+option hashes don't trigger repeated work. The cache is bounded — defaulting to 1000
+entries per direction — and applications that generate many distinct option hashes
+can raise the ceiling at runtime:
+
+```ruby
+MultiJson::OptionsCache.max_cache_size = 5000
+```
+
+`max_cache_size` must be a positive integer; `0`, negative values, and
+non-integers raise `ArgumentError`.
+
+Lowering the limit only takes effect for *new* inserts; existing cache
+entries are left in place until normal eviction trims them below the
+new ceiling. Call `MultiJson::OptionsCache.reset` if you want to evict
+immediately.
 
 The `use` method, which sets the MultiJSON adapter, takes either a symbol or a
 class (to allow for custom JSON parsers) that responds to both `.load` and `.dump`
@@ -39,37 +70,84 @@ at the class level.
 When MultiJSON fails to load the specified adapter, it'll throw `MultiJson::AdapterError`
 which inherits from `ArgumentError`.
 
-MultiJSON tries to have intelligent defaulting. That is, if you have any of the
-supported engines already loaded, it will utilize them before attempting to
-load any. When loading, libraries are ordered by speed. First Oj, then Yajl,
-then the JSON gem, then JSON pure. If no other JSON library is available,
-MultiJSON falls back to [OkJson][], a simple, vendorable JSON parser.
+### Writing a custom adapter
+
+A custom adapter is any class that responds to two class methods plus
+defines a `ParseError` constant:
 
-## Supported JSON Engines
+```ruby
+class MyAdapter
+  ParseError = Class.new(StandardError)
+
+  def self.load(string, options)
+    # parse string into a Ruby object, raising ParseError on failure
+  end
+
+  def self.dump(object, options)
+    # serialize object to a JSON string
+  end
+end
 
-* [Oj][oj] Optimized JSON by Peter Ohler
-* [Yajl][yajl] Yet Another JSON Library by Brian Lopez
-* [JSON][json-gem] The default JSON gem with C-extensions (ships with Ruby 1.9+)
-* [JSON Pure][json-gem] A Ruby variant of the JSON gem
-* [NSJSONSerialization][nsjson] Wrapper for Apple's NSJSONSerialization in the Cocoa Framework (MacRuby only)
-* [gson.rb][gson] A Ruby wrapper for google-gson library (JRuby only)
-* [JrJackson][jrjackson] JRuby wrapper for Jackson (JRuby only)
-* [OkJson][okjson] A simple, vendorable JSON parser
+MultiJson.use(MyAdapter)
+```
+
+`ParseError` is required: `MultiJson.load` rescues `MyAdapter::ParseError`
+to wrap parse failures in `MultiJson::ParseError`, and an adapter that
+omits the constant raises `MultiJson::AdapterError` on the first parse
+attempt instead of producing a confusing `NameError`.
+
+For more, inherit from `MultiJson::Adapter` to pick up shared option
+merging, the `defaults :load, ...` / `defaults :dump, ...` DSL, and the
+blank-input short-circuit. The built-in adapters in
+`lib/multi_json/adapters/` are working examples.
+
+MultiJSON tries to have intelligent defaulting. If any supported library is
+already loaded, MultiJSON uses it before attempting to load others. When no
+backend is preloaded, MultiJSON walks its preference list and uses the first
+one that loads successfully:
+
+1. `fast_jsonparser`
+2. `oj`
+3. `yajl-ruby`
+4. `jrjackson`
+5. The JSON gem
+6. `gson`
+
+This order is a best-effort historical ranking by typical parse/dump
+throughput on representative workloads, not a guaranteed benchmark. Real-world
+performance depends on the document shape, the Ruby implementation, and
+whether you're calling `load` or `dump`. The JSON gem is a Ruby default gem,
+so it's always available as a last-resort fallback on any supported Ruby. If
+you have a workload where a different backend is faster, set it explicitly
+with `MultiJson.use(:your_adapter)`.
+
+## Gem Variants
+
+MultiJSON ships as two platform-specific gems. Bundler and RubyGems
+automatically select the correct variant for your Ruby implementation:
+
+|                                                | `ruby` platform (MRI) | `java` platform (JRuby) |
+| ---------------------------------------------- | :---: | :---: |
+| Runtime dependency                             | none  | [concurrent-ruby][concurrent-ruby] `~> 1.2` |
+| [`fast_jsonparser`][fast_jsonparser] adapter   |   ✓   |       |
+| [`oj`][oj] adapter                             |   ✓   |       |
+| [`yajl`][yajl] adapter                         |   ✓   |       |
+| [`json_gem`][json-gem] adapter                 |   ✓   |   ✓   |
+| [`gson`][gson] adapter                         |       |   ✓   |
+| [`jr_jackson`][jrjackson] adapter              |       |   ✓   |
+| `OptionsCache` thread-safe store               | `Hash` + `Mutex` | `Concurrent::Map` |
 
 ## Supported Ruby Versions
-This library aims to support and is [tested against][travis] the following Ruby
+
+This library aims to support and is [tested against](https://github.com/sferik/multi_json/actions/workflows/tests.yml) the following Ruby
 implementations:
 
-* Ruby 1.8
-* Ruby 1.9
-* Ruby 2.0
-* Ruby 2.1
-* Ruby 2.2
-* Ruby 2.4
-* Ruby 2.5
-* Ruby 2.6
-* Ruby 2.7
-* [JRuby][]
+- Ruby 3.2
+- Ruby 3.3
+- Ruby 3.4
+- Ruby 4.0
+- [JRuby][jruby] 10.0 (targets Ruby 3.4 compatibility)
+- [TruffleRuby][truffleruby] 33.0 (native and JVM)
 
 If something doesn't work in one of these implementations, it's a bug.
 
@@ -100,22 +178,27 @@ spec.add_dependency 'multi_json', '~> 1.0'
 ```
 
 ## Copyright
-Copyright (c) 2010-2018 Michael Bleigh, Josh Kalderimis, Erik Michaels-Ober,
-and Pavel Pravosud. See [LICENSE][] for details.
 
-[codeclimate]: https://codeclimate.com/github/intridea/multi_json
+Copyright (c) 2010-2026 Erik Berlin, Michael Bleigh, Josh Kalderimis, and Pavel
+Pravosud. See [LICENSE][license] for details.
+
+[concurrent-ruby]: https://github.com/ruby-concurrency/concurrent-ruby
+[docs]: https://github.com/sferik/multi_json/actions/workflows/docs.yml
+[fast_jsonparser]: https://github.com/anilmaurya/fast_jsonparser
 [gem]: https://rubygems.org/gems/multi_json
 [gson]: https://github.com/avsej/gson.rb
 [jrjackson]: https://github.com/guyboertje/jrjackson
 [jruby]: http://www.jruby.org/
 [json-gem]: https://github.com/flori/json
-[json-pure]: https://github.com/flori/json
 [license]: LICENSE.md
+[linter]: https://github.com/sferik/multi_json/actions/workflows/linter.yml
 [macruby]: http://www.macruby.org/
-[nsjson]: https://developer.apple.com/library/ios/#documentation/Foundation/Reference/NSJSONSerialization_Class/Reference/Reference.html
+[mutant]: https://github.com/sferik/multi_json/actions/workflows/mutant.yml
 [oj]: https://github.com/ohler55/oj
-[okjson]: https://github.com/kr/okjson
 [pvc]: http://docs.rubygems.org/read/chapter/16#page74
+[qlty]: https://qlty.sh/gh/sferik/projects/multi_json
 [semver]: http://semver.org/
-[travis]: http://travis-ci.org/intridea/multi_json
+[tests]: https://github.com/sferik/multi_json/actions/workflows/tests.yml
+[truffleruby]: https://www.graalvm.org/ruby/
+[typecheck]: https://github.com/sferik/multi_json/actions/workflows/typecheck.yml
 [yajl]: https://github.com/brianmario/yajl-ruby

data/lib/multi_json/adapter.rb

@@ -1,49 +1,182 @@
-require 'singleton'
-require 'multi_json/options'
+# frozen_string_literal: true
+
+require "singleton"
+require_relative "options"
 
 module MultiJson
+  # Base class for JSON adapter implementations
+  #
+  # Each adapter wraps a specific JSON library (Oj, JSON gem, etc.) and
+  # provides a consistent interface. Uses Singleton pattern so each adapter
+  # class has exactly one instance.
+  #
+  # Subclasses must implement:
+  # - #load(string, options) -> parsed object
+  # - #dump(object, options) -> JSON string
+  #
+  # @api private
   class Adapter
     extend Options
     include Singleton
 
     class << self
+      BLANK_PATTERN = /\A\s*\z/
+      VALID_DEFAULTS_ACTIONS = %i[load dump].freeze
+      private_constant :BLANK_PATTERN, :VALID_DEFAULTS_ACTIONS
+
+      # Get default load options, walking the superclass chain
+      #
+      # Returns the closest ancestor's `@default_load_options` ivar so a
+      # parent class calling {.defaults} after a subclass has been
+      # defined still propagates to the subclass. Falls back to the
+      # shared frozen empty hash when no ancestor has defaults set.
+      #
+      # @api private
+      # @return [Hash] frozen options hash
+      def default_load_options
+        walk_default_options(:@default_load_options)
+      end
+
+      # Get default dump options, walking the superclass chain
+      #
+      # @api private
+      # @return [Hash] frozen options hash
+      def default_dump_options
+        walk_default_options(:@default_dump_options)
+      end
+
+      # DSL for setting adapter-specific default options
+      #
+      # ``action`` must be ``:load`` or ``:dump``; ``value`` must be a
+      # Hash. Both arguments are validated up front so a typo at the
+      # adapter's class definition fails fast instead of producing a
+      # silent no-op default that crashes later in the merge path.
+      #
+      # @api private
+      # @param action [Symbol] :load or :dump
+      # @param value [Hash] default options for the action
+      # @return [Hash] the frozen options hash
+      # @raise [ArgumentError] when action is anything other than :load
+      #   or :dump, or when value isn't a Hash
+      # @example Set load defaults for an adapter
+      #   class MyAdapter < MultiJson::Adapter
+      #     defaults :load, symbolize_keys: false
+      #   end
       def defaults(action, value)
-        metaclass = class << self; self; end
+        raise ArgumentError, "expected action to be :load or :dump, got #{action.inspect}" unless VALID_DEFAULTS_ACTIONS.include?(action)
+        raise ArgumentError, "expected value to be a Hash, got #{value.class}" unless value.is_a?(Hash)
 
-        metaclass.instance_eval do
-          define_method("default_#{action}_options") { value }
-        end
+        instance_variable_set(:"@default_#{action}_options", value.freeze)
       end
 
+      # Parse a JSON string into a Ruby object
+      #
+      # @api private
+      # @param string [String, #read] JSON string or IO-like object
+      # @param options [Hash] parsing options
+      # @return [Object, nil] parsed object or nil for blank input
       def load(string, options = {})
         string = string.read if string.respond_to?(:read)
-        fail self::ParseError if blank?(string)
-        instance.load(string, cached_load_options(options))
+        return nil if blank?(string)
+
+        instance.load(string, merged_load_options(options))
       end
 
+      # Serialize a Ruby object to JSON
+      #
+      # @api private
+      # @param object [Object] object to serialize
+      # @param options [Hash] serialization options
+      # @return [String] JSON string
       def dump(object, options = {})
-        instance.dump(object, cached_dump_options(options))
+        instance.dump(object, merged_dump_options(options))
       end
 
-    private
+      private
 
+      # Walk the superclass chain looking for a default options ivar
+      #
+      # Stops at the first ancestor whose ``ivar`` is set and returns
+      # that value. Returns {Options::EMPTY_OPTIONS} when no ancestor
+      # has the ivar set, so adapters without defaults always observe a
+      # frozen empty hash instead of nil.
+      #
+      # @api private
+      # @param ivar [Symbol] ivar name (`:@default_load_options` or `:@default_dump_options`)
+      # @return [Hash] frozen options hash
+      def walk_default_options(ivar)
+        # @type var klass: Class?
+        klass = self
+        while klass
+          return klass.instance_variable_get(ivar) if klass.instance_variable_defined?(ivar)
+
+          klass = klass.superclass
+        end
+        Options::EMPTY_OPTIONS
+      end
+
+      # Checks if the input is blank (nil, empty, or whitespace-only)
+      #
+      # The dominant call path arrives with a non-blank string starting
+      # with ``{`` or ``[`` (the JSON object/array sigils), so a
+      # ``start_with?`` short-circuit skips the regex entirely on the
+      # hot path. Falls through to the full check for everything else
+      # — strings, numbers, booleans, ``null``, whitespace-prefixed
+      # input — at which point ``String#scrub`` is only invoked when
+      # the input has invalid encoding so the common valid-UTF-8 path
+      # doesn't allocate a scrubbed copy on every call. Scrubbing
+      # replaces invalid bytes with U+FFFD before the regex runs so a
+      # string with bad bytes is still treated as non-blank without a
+      # broad rescue.
+      #
+      # @api private
+      # @param input [String, nil] input to check
+      # @return [Boolean] true if input is blank
       def blank?(input)
-        input.nil? || /\A\s*\z/ === input
-      rescue ArgumentError # invalid byte sequence in UTF-8
-        false
+        return true if input.nil? || input.empty?
+        return false if input.start_with?("{", "[")
+
+        BLANK_PATTERN.match?(input.valid_encoding? ? input : input.scrub)
       end
 
-      def cached_dump_options(options)
-        OptionsCache.fetch(:dump, options) do
-          dump_options(options).merge(MultiJson.dump_options(options)).merge!(options)
+      # Merges dump options from adapter, global, and call-site
+      #
+      # @api private
+      # @param options [Hash] call-site options
+      # @return [Hash] merged options hash
+      def merged_dump_options(options)
+        cache_key = strip_adapter_key(options)
+        OptionsCache.dump.fetch(cache_key) do
+          dump_options(cache_key).merge(MultiJson.dump_options(cache_key)).merge!(cache_key)
         end
       end
 
-      def cached_load_options(options)
-        OptionsCache.fetch(:load, options) do
-          load_options(options).merge(MultiJson.load_options(options)).merge!(options)
+      # Merges load options from adapter, global, and call-site
+      #
+      # @api private
+      # @param options [Hash] call-site options
+      # @return [Hash] merged options hash
+      def merged_load_options(options)
+        cache_key = strip_adapter_key(options)
+        OptionsCache.load.fetch(cache_key) do
+          load_options(cache_key).merge(MultiJson.load_options(cache_key)).merge!(cache_key)
         end
       end
+
+      # Removes the :adapter key from options for cache key
+      #
+      # Returns a shared frozen empty hash for the common no-options call
+      # path so the hot path avoids allocating a fresh hash on every call.
+      #
+      # @api private
+      # @param options [Hash, #to_h] original options (may be JSON::State or similar)
+      # @return [Hash] frozen options without :adapter key
+      def strip_adapter_key(options)
+        options = options.to_h unless options.is_a?(Hash)
+        return Options::EMPTY_OPTIONS if options.empty? || (options.size == 1 && options.key?(:adapter))
+
+        options.except(:adapter).freeze
+      end
     end
   end
 end

data/lib/multi_json/adapter_error.rb

@@ -1,15 +1,42 @@
+# frozen_string_literal: true
+
 module MultiJson
+  # Raised when an adapter cannot be loaded or is not recognized
+  #
+  # @api public
   class AdapterError < ArgumentError
-    attr_reader :cause
+    # Create a new AdapterError
+    #
+    # @api public
+    # @param message [String, nil] error message
+    # @param cause [Exception, nil] the original exception
+    # @return [AdapterError] new error instance
+    # @example
+    #   AdapterError.new("Unknown adapter", cause: original_error)
+    def initialize(message = nil, cause: nil)
+      super(message)
+      set_backtrace(cause.backtrace) if cause
+    end
 
+    # Build an AdapterError from an original exception
+    #
+    # The original exception's class name is included in the message
+    # so a downstream consumer reading just the AdapterError can tell
+    # whether the underlying failure was a `LoadError`, an
+    # `ArgumentError` from the spec validator, or some other class
+    # without having to look at `error.cause` separately.
+    #
+    # @api public
+    # @param original_exception [Exception] the original load error
+    # @return [AdapterError] new error with formatted message
+    # @example
+    #   AdapterError.build(LoadError.new("cannot load such file"))
     def self.build(original_exception)
-      message = "Did not recognize your adapter specification (#{original_exception.message})."
-      new(message).tap do |exception|
-        exception.instance_eval do
-          @cause = original_exception
-          set_backtrace original_exception.backtrace
-        end
-      end
+      new(
+        "Did not recognize your adapter specification " \
+        "(#{original_exception.class}: #{original_exception.message}).",
+        cause: original_exception
+      )
     end
   end
 end