multi_json 1.19.1 → 1.20.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d32c6ecf7a376a7280adac3692fd9b256d0934b1cff4724955b815a76a8b8d1
-  data.tar.gz: f273e11d29ac7ec97954410f1b9af76d4e3f43a299c0507583371e15d01af0cd
+  metadata.gz: fbba8097011550d30c5962bdd828a95b431ab54cc9a6d831844e78c78f2ddc74
+  data.tar.gz: 767ba488de4f71c7503d69126130b88d904f656ec12cd2b0c039a1d66c39e594
 SHA512:
-  metadata.gz: 01ae1a673f2ccb2bbe25ee7e960f1e2984859495c50bdeeab4e1c5aa0315915f2b8f815b88a23bd5de781fed52d35b0ab8f0986a1aad8d74a3e055d554347107
-  data.tar.gz: 69f7aa6acd371a2852f12a616d0501f33acd85c01ac0204669ef4c30ebb058b7399cccb4b0fa830c41ec0a4cdd2ad8273ca134d9915b59dc53c4f5c4f6bf664c
+  metadata.gz: a0e46b45475da5fa524fdfc00c02b10bf9a3c677d3702bf81fa1bfaef278dc219a7720f082cc1a8edbc5fe07e2aa83e92a87ec2a7057a42edabd90a211fde34e
+  data.tar.gz: 650953b9efc5ba89c84cb751c206972e8d95923c5b466558a97c340666a31b71645943e83b0186076cbf9a843da3dd306c3fdb654911873797bedf89e763e7d7

data/CHANGELOG.md

@@ -1,5 +1,89 @@
 # Changelog
 
+## 1.20.1
+* Fix `JsonGem#load` raising `ParseError` on ASCII-8BIT strings that contain valid UTF-8 bytes ([#64](https://github.com/sferik/multi_json/issues/64)). Ruby HTTP clients tag response bodies as ASCII-8BIT by default; the 1.20.0 change from `force_encoding` to `encode` broke the dominant real-world case by trying to transcode each byte individually. Switch back to `force_encoding` followed by a `valid_encoding?` guard so genuinely invalid byte sequences still surface as `ParseError`.
+* Validate custom adapters during `MultiJson.use` and `MultiJson.load`/`dump` with an `:adapter` option, raising `MultiJson::AdapterError` immediately if the adapter does not respond to `.load`, `.dump`, or define a `ParseError` constant.
+* Validate `OptionsCache.max_cache_size=` to reject `nil`, zero, negative, and non-integer values with a clear `ArgumentError`.
+
+## 1.20.0
+* Drop the `UnannotatedEmptyCollection` Steep diagnostic override by inline-annotating `Options::EMPTY_OPTIONS` with `#: options` and routing `MultiJson.current_adapter`'s `||=` fallback through that constant. Also enable rubocop's `Layout/LeadingCommentSpace` `AllowSteepAnnotation` / `AllowRBSInlineAnnotation` so future inline `#:` casts don't need a per-line disable.
+* Hoist the `block_given?` check in `MutexStore#fetch` outside `@mutex.synchronize` so the no-block read path runs the check once per call instead of inside the critical section.
+* Short-circuit `Adapter.blank?` on inputs that start with `{` or `[` so the dominant JSON object and array load paths skip the blank-pattern regex entirely.
+* Drop the `(...)` argument forwarding in `MultiJson::Options#load_options`, `dump_options`, `resolve_options`, and `invoke_callable` in favor of explicit `*args` so the signatures document that they forward positional arguments to a callable provider and nothing else.
+* Collapse the five `MultiJson::Concurrency.synchronize_*` wrapper methods into a single `Concurrency.synchronize(name, &block)` keyed by symbol, with the mutex catalog in a `MUTEXES` hash. The synchronization surface is now one method instead of five and adding a new mutex is a one-line entry.
+* Walk the superclass chain manually in `Adapter.walk_default_options` instead of allocating an `ancestors` array on every call. The dump/load hot path no longer pays for an iteration over the (mostly module) ancestor list when looking up an adapter's defaults.
+* Add a `# frozen_string_literal: true` magic comment to every Ruby file in `lib/` and `test/`, and flip the `Style/FrozenStringLiteralComment` rubocop cop to `EnforcedStyle: always` so future files inherit the freeze.
+* Include the original exception's class name in `MultiJson::AdapterError.build`'s formatted message so a downstream consumer reading just the wrapped error can distinguish a `LoadError` from a validator `ArgumentError` without having to inspect `error.cause` separately.
+* Mark the five `MultiJson::Concurrency` mutex constants as `private_constant` and add matching `synchronize_*` wrapper methods so callers don't reach into the module's internals.
+* DRY up `lib/multi_json/deprecated.rb` with a small `deprecate_alias` / `deprecate_method` DSL so adding or removing a deprecation is a one-liner instead of a 4-line copy of the warn-then-delegate template.
+* Hoist a shared `Gson::Decoder` and `Gson::Encoder` to handle the empty-options case in the JRuby `Gson` adapter so the dominant `MultiJson.load(json)` / `MultiJson.dump(obj)` call path no longer allocates a fresh decoder/encoder per call.
+* Memoize the per-adapter `ParseError` lookup in `MultiJson.parse_error_class_for` so the constant resolution runs at most once per adapter, instead of on every `MultiJson.load` call.
+* Walk the superclass chain in `Adapter.default_load_options` / `default_dump_options` instead of copying the parent's defaults into the subclass at inheritance time, so a parent calling `defaults :load, ...` after a subclass has been defined now propagates to the subclass.
+* Hold `@eviction_mutex` around `ConcurrentStore#reset`'s `@cache.clear` so a JRuby fetcher in the middle of its evict-then-insert sequence cannot interleave with a concurrent reset, mirroring `MutexStore#reset`'s mutex usage.
+* Collect the five process-wide mutexes that protect MultiJson's lazy initializers and adapter swap into a new `MultiJson::Concurrency` module so the library's concurrency surface is documented in one place.
+* Replace the per-adapter `loaded` lambdas in `AdapterSelector::ADAPTERS` with constant name strings, walked through `Object.const_defined?` directly. The lookup table is half as large and no longer holds six closure objects whose only job was to call `defined?`.
+* Wrap `AdapterSelector#default_adapter_excluding` in `DEFAULT_ADAPTER_MUTEX` so concurrent callers can't both walk the detection chain and double-fire `fallback_adapter`'s one-time warning.
+* Raise a clear `MultiJson::AdapterError` when a custom adapter passed to `MultiJson.load` does not define a `ParseError` constant, instead of letting the bare `NameError` from the rescue clause propagate.
+* Drop the duplicate `Adapter::EMPTY_OPTIONS` constant in favor of the `MultiJson::Options::EMPTY_OPTIONS` it was shadowing.
+* Defer the `fast_jsonparser` adapter's dump-delegate resolution until the first `dump` call instead of locking it in at file load time. The adapter no longer inherits from another adapter, so loading `multi_json/adapters/fast_jsonparser` before `oj` no longer locks the dump path to whichever adapter happened to be available at that moment.
+* Make the lazy `default_load_options` and `default_dump_options` initializers in `MultiJson::Options` thread-safe so two threads accessing an adapter's defaults for the first time can't both run the `||=` initializer.
+* Make `AdapterSelector#default_adapter`'s lazy `||=` initializer thread-safe so two threads racing past the unset `@default_adapter` ivar can't both run detection (and double-emit the fallback warning in the no-adapters-installed branch).
+* Wrap `MultiJson.use`'s `OptionsCache.reset` and `@adapter` swap in a mutex so two threads calling `use` concurrently can't interleave their cache reset and adapter assignment.
+* Stop relying on `Oj::ParseError`'s `::SyntaxError` ancestor when matching exceptions in `Oj::ParseError.===`. Walk the exception's ancestor chain by class name instead, so a future Oj release that re-parents its error class doesn't silently break our rescue clauses.
+* Improve `AdapterSelector#load_adapter`'s error message for unrecognized adapter specs so it names the expected types and shows the offender's `inspect` output instead of just `to_s`.
+* Validate the `value` argument in `Adapter.defaults` so a non-Hash (e.g. `defaults :load, "oops"`) raises `ArgumentError` at definition time instead of crashing later in the merge path.
+* Skip `String#scrub` in `Adapter.blank?` when the input is already valid UTF-8 so the common load path no longer allocates a scrubbed copy on every call.
+* Move `Oj#load`'s `:symbolize_keys` translation into a private `translate_load_options` helper that drops the redundant `:symbolize_keys` passthrough alongside `:symbol_keys`, mirroring the cleanup already in `JsonGem#load`.
+* Skip the per-call hash merge in `JsonGem#dump` when `pretty: true` is the only option, passing `PRETTY_STATE_PROTOTYPE` directly.
+* Type-check the `Yajl`, `JrJackson`, and `Gson` adapter wrappers under Steep, with stubbed RBS sigs for the underlying libraries living in `sig/external_libraries.rbs`.
+* Unify `LOADED_ADAPTER_DETECTORS` and `REQUIREMENT_MAP` in `AdapterSelector` into a single `ADAPTERS` source-of-truth so the require path and detection lambda for each adapter live in one place.
+* Extract deprecated public API (`decode`, `encode`, `engine`, `engine=`, `default_engine`, `with_engine`, `default_options`, `default_options=`, `cached_options`, `reset_cached_options!`) into `lib/multi_json/deprecated.rb` and drop the matching `Style/Documentation`, `Style/ModuleFunction`, and `Style/OpenStructUse` rubocop opt-outs.
+* Validate the `action` argument in `Adapter.defaults` so a typo (e.g. `defaults :encode, ...`) raises `ArgumentError` at definition time instead of silently producing a no-op default.
+* Drop the stale `ok_json` reference from the `fast_jsonparser` adapter's docstring.
+* Remove the `MultiJson::REQUIREMENT_MAP` legacy alias; the canonical map already lives on `MultiJson::AdapterSelector`.
+* Drop the dead `JrJackson` dump arity branch (and its SimpleCov filter). JrJackson 0.4.18+ accepts an options hash as the second argument to `Json.dump`.
+* Drop the redundant `options.except(:adapter)` allocation in `JsonGem#dump`; `Adapter.merged_dump_options` already strips `:adapter` before the cached hash reaches the adapter.
+* Forward all merged options through `Yajl#load` instead of honoring only `:symbolize_keys`.
+* Tighten `Adapter.blank?` so it scrubs invalid UTF-8 bytes up front instead of swallowing every `ArgumentError` from the underlying `String` calls.
+* Guard `ConcurrentStore` eviction against a TOCTOU race so two concurrent JRuby threads cannot both pass the size check and briefly exceed `OptionsCache.max_cache_size`.
+* Synchronize `warn_deprecation_once` so concurrent fibers and threads cannot race past the membership check and emit the same one-time deprecation warning twice.
+* Stop resetting `OptionsCache` when `MultiJson.use` raises so a failed `use(:nonexistent)` no longer discards the cached entries belonging to the still-active previous adapter.
+* Stop mutating cached options in `JsonGem#load`, mirroring the cache-pollution fix already in place for `Oj#load`.
+* Empty the mutant ignore list. The `Gson` and `JrJackson` ignores were dead — those adapters ship in the java-platform gem and aren't present when mutant runs on MRI — and `Store#reset`'s mutex wrapper is now directly tested by stubbing `Mutex#synchronize`.
+* Remove the vendored `ok_json` adapter. The json gem has been a Ruby default gem since 1.9, so an external pure-Ruby fallback is no longer needed on any supported Ruby version. The last-resort fallback when no other JSON library can be loaded is now `json_gem`. The `ConvertibleHashKeys` helper module, which only `ok_json` used, is also removed.
+* Surface parse error locations as `error.line` and `error.column` on `MultiJson::ParseError`, extracted from the underlying adapter's message for adapters that include one (Oj, the json gem).
+* Make `MultiJson::OptionsCache.max_cache_size` configurable so applications that generate many distinct option hashes can raise the cache ceiling at runtime.
+* Reorganize `lib/multi_json.rb` into clearer sections and document why both the `module_function` and singleton-only definition patterns coexist.
+* Restructure `OptionsCache` backend selection so MRI and JRuby execute the same physical `require_relative` line, restoring JRuby's line coverage threshold to 100%.
+* Drop the `ALIASES` constant in `AdapterSelector` in favor of an inline check; the only entry, `jrjackson` → `jr_jackson`, is now inlined into `load_adapter_by_name`.
+* Document the `fast_jsonparser` adapter's parent class freeze at file load time.
+* Stop mass-requiring adapter gems at the top of `adapter_selection_test.rb`, which polluted the global require cache and let later tests silently depend on adapters they had not explicitly loaded.
+* Restore the mutex around `MutexStore#reset` for TruffleRuby, where the unguarded clear could race with concurrent fetches in a way the MRI GVL otherwise prevents.
+* Fix `TestHelpers.yajl?` to check the actual `yajl-ruby` gem name.
+* [Stop requiring the `oj` gem from the `fast_jsonparser` adapter](https://github.com/sferik/multi_json/issues/63): `fast_jsonparser` only implements parsing, so the adapter's `dump` side now inherits from whichever adapter MultiJson would otherwise pick (oj → yajl → jr_jackson → json_gem → gson → ok_json). Users who install `fast_jsonparser` no longer need to also install `oj`.
+* [Split the gem into `ruby` and `java` platform variants](https://github.com/sferik/multi_json/commit/ca2c747570335f8d3b6b0904aae6ace41329aedd): the `java` variant adds `concurrent-ruby ~> 1.2` as a runtime dependency and ships the `gson` and `jr_jackson` adapters; the `ruby` variant has no runtime dependencies and ships the MRI-only adapters. Bundler selects the correct variant automatically.
+* [Drop Oj 2.x compatibility branch](https://github.com/sferik/multi_json/commit/93897a45e2b2f3f6fa047ee00fc1e879ae137ec1): the Oj adapter now requires Oj `~> 3.0`.
+* [Drop support for Ruby 3.0, Ruby 3.1, and JRuby 9.4](https://github.com/sferik/multi_json/commit/bc4547a5cee4d66294f2a1be04fe61f9d49235cd).
+* [Add Ruby 4.0 to the CI matrix](https://github.com/sferik/multi_json/commit/bdf4999ea0c81f79c208e5fafb63f7474571b687).
+* [Make `with_adapter` overrides fiber-local](https://github.com/sferik/multi_json/commit/7f7ce0e68f094bb9a26bf37a950c4794dc8e7292) so concurrent fibers and threads each observe their own adapter without racing on a shared module variable.
+* [Raise `MultiJson::ParseError` on invalid UTF-8 in the `json_gem` adapter](https://github.com/sferik/multi_json/commit/2b5d14548fc67c5fdcaaee9b14d9f3eefe1f3493) instead of silently reinterpreting bytes with `force_encoding`.
+* [Warn once for deprecated method aliases](https://github.com/sferik/multi_json/commit/5390bf311567388056724743121a665adab8ae8d): `decode`, `encode`, `engine`, `engine=`, `default_engine`, and `with_engine` now emit a one-time deprecation warning on first call and are scheduled for removal in a future major release.
+* [Emit deprecation warnings only once per process](https://github.com/sferik/multi_json/commit/118f608c43aacb2ad36aa5f70b9084d48a9877c9) for `default_options`, `default_options=`, `cached_options`, and `reset_cached_options!` instead of on every call.
+* [Document public API methods as `@api public`](https://github.com/sferik/multi_json/commit/5f3bd5397800cbf4b8f3a522e91364de1ad9079d) so `load`, `dump`, `use`, `with_adapter`, `current_adapter`, `adapter`, `load_options`, and `dump_options` appear in generated docs.
+* [Add YARD documentation for the `Adapters` module and `ParseError` constants](https://github.com/sferik/multi_json/commit/3bc3beb76987a5711bf6c94ab176d5a84a42b063).
+* [Stop mutating cached options in `Oj#load`](https://github.com/sferik/multi_json/commit/091d4f046dfb1d85816b04ef68c0850e5a97acdf): the adapter previously assigned `options[:symbol_keys]` on the shared cached hash, slowly polluting it with extra keys.
+* [Stop mutating cached options in `OjCommon#prepare_dump_options`](https://github.com/sferik/multi_json/commit/089892e387b56036840b58b61593ce2b80fd72d6): `merge!(PRETTY_STATE_PROTOTYPE)` on the cached options hash removed `:pretty` and added prototype keys on every call, producing accidentally-correct results through cache reuse.
+* [Call `to_h` on options to properly handle `JSON::State` objects](https://github.com/sferik/multi_json/commit/821ea32d5cafc223983b24b3260a1d4112aefab9).
+* [Avoid allocating an options hash on the `dump`/`load` hot path](https://github.com/sferik/multi_json/commit/89a397718fff9e6cc5af8b7ef9fa19494894e6ce) by reusing a shared frozen empty hash for the no-options case.
+* [Short-circuit empty input in `Adapter.blank?`](https://github.com/sferik/multi_json/commit/d3081a64eaf7755610a29c602dc6f0c5678643c6) before falling back to the regex match.
+* [Replace the `LOADERS` strategy table with a `case` statement](https://github.com/sferik/multi_json/commit/562331a002dc87052797c53769610a719699c33c) in `AdapterSelector#load_adapter`.
+* [Move `REQUIREMENT_MAP` from `MultiJson` into `AdapterSelector`](https://github.com/sferik/multi_json/commit/ab371e70d63b840386a3cf264611c2298c7c8250); `MultiJson::REQUIREMENT_MAP` remains as a deprecated alias.
+* [Fix Bundler 4.0 permission error in CI](https://github.com/sferik/multi_json/commit/1fe4514e641e34dcf3ec9b62a2a76bfe0120c708).
+* [Revert the Steep removal](https://github.com/sferik/multi_json/commit/883be03219d5178f83381333c3a354f59b4c8117) and restore the Steepfile, sig directory, and typecheck workflow.
+* [Add workflow badges for linter, mutant, steep, and docs](https://github.com/sferik/multi_json/commit/88cf1bea1fb3056ad3a7c0f8ca828e194ee895dd).
+* [Bump `actions/checkout` from 4 to 6](https://github.com/sferik/multi_json/commit/587f246d9ffd6991417af771fa0ce7059b337c40).
+* [Update copyright year and alphabetize contributors by last name](https://github.com/sferik/multi_json/commit/233fb0ee1a375279d83c06ff6f702ec17d695b88).
+
 ## 1.19.1
 * [Restore deprecated encode/decode methods](https://github.com/sferik/multi_json/commit/c5bf2fc95dfdde6b30d63fefb0b2f4aa29633969)
 

data/CONTRIBUTING.md

@@ -41,8 +41,9 @@ system. Ideally, a bug report should include a pull request with failing tests.
 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. Add, commit, and push your changes.
-12. [Submit a pull request][pr] that summarizes *what* changes you made and
+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.

data/LICENSE.md

@@ -1,4 +1,4 @@
-Copyright (c) 2010-2025 Michael Bleigh, Josh Kalderimis, Erik Berlin, 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](https://github.com/sferik/multi_json/actions/workflows/tests.yml/badge.svg)][build]
+[![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,34 +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 fast_jsonparser,
-then Oj, then Yajl, then the JSON gem. 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
 
-- [fast_jsonparser][fast_jsonparser] Fast JSON parser by Anil Maurya
-- [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+)
-- [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](https://github.com/sferik/multi_json/actions/workflows/ci.yml) 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 3.0
-- Ruby 3.1
 - Ruby 3.2
 - Ruby 3.3
 - Ruby 3.4
-- [JRuby][jruby] 9.4 (targets Ruby 3.1 compatibility)
+- 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.
 
@@ -98,21 +179,26 @@ spec.add_dependency 'multi_json', '~> 1.0'
 
 ## Copyright
 
-Copyright (c) 2010-2025 Michael Bleigh, Josh Kalderimis, Erik Berlin,
-and Pavel Pravosud. See [LICENSE][license] for details.
+Copyright (c) 2010-2026 Erik Berlin, Michael Bleigh, Josh Kalderimis, and Pavel
+Pravosud. See [LICENSE][license] for details.
 
-[build]: https://github.com/sferik/multi_json/actions/workflows/tests.yml
+[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
 [license]: LICENSE.md
+[linter]: https://github.com/sferik/multi_json/actions/workflows/linter.yml
 [macruby]: http://www.macruby.org/
+[mutant]: https://github.com/sferik/multi_json/actions/workflows/mutant.yml
 [oj]: https://github.com/ohler55/oj
-[okjson]: https://github.com/kr/okjson
-[fast_jsonparser]: https://github.com/anilmaurya/fast_jsonparser
 [pvc]: http://docs.rubygems.org/read/chapter/16#page74
 [qlty]: https://qlty.sh/gh/sferik/projects/multi_json
 [semver]: http://semver.org/
+[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,3 +1,5 @@
+# frozen_string_literal: true
+
 require "singleton"
 require_relative "options"
 
@@ -19,27 +21,51 @@ module MultiJson
 
     class << self
       BLANK_PATTERN = /\A\s*\z/
-      private_constant :BLANK_PATTERN
+      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
 
-      # Hook called when a subclass is created
+      # Get default dump options, walking the superclass chain
       #
       # @api private
-      # @param subclass [Class] the new subclass
-      # @return [void]
-      def inherited(subclass)
-        super
-        # Propagate default options to subclasses
-        subclass.instance_variable_set(:@default_load_options, @default_load_options) if defined?(@default_load_options)
-        subclass.instance_variable_set(:@default_dump_options, @default_dump_options) if defined?(@default_dump_options)
+      # @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)
+        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)
+
         instance_variable_set(:"@default_#{action}_options", value.freeze)
       end
 
@@ -68,16 +94,49 @@ module MultiJson
 
       private
 
-      # Checks if the input is blank (nil or whitespace-only)
+      # 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? || BLANK_PATTERN.match?(input)
-      rescue ArgumentError
-        # Invalid byte sequence in UTF-8 - treat as non-blank
-        false
+        return true if input.nil? || input.empty?
+        return false if input.start_with?("{", "[")
+
+        BLANK_PATTERN.match?(input.valid_encoding? ? input : input.scrub)
       end
 
       # Merges dump options from adapter, global, and call-site
@@ -106,10 +165,16 @@ module MultiJson
 
       # 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] original options
+      # @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

data/lib/multi_json/adapter_error.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module MultiJson
   # Raised when an adapter cannot be loaded or is not recognized
   #
@@ -18,6 +20,12 @@ module MultiJson
 
     # 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
@@ -25,7 +33,8 @@ module MultiJson
     #   AdapterError.build(LoadError.new("cannot load such file"))
     def self.build(original_exception)
       new(
-        "Did not recognize your adapter specification (#{original_exception.message}).",
+        "Did not recognize your adapter specification " \
+        "(#{original_exception.class}: #{original_exception.message}).",
         cause: original_exception
       )
     end