multi_json 1.15.0 → 1.20.1

data/lib/multi_json/deprecated.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+# Deprecated public API kept around for one major release
+#
+# Each method here emits a one-time deprecation warning on first call and
+# delegates to its current-API counterpart. The whole file is loaded by
+# {MultiJson} so the deprecation surface stays out of the main module
+# definition.
+#
+# @api private
+module MultiJson
+  class << self
+    private
+
+    # Define a deprecated alias that delegates to a new method name
+    #
+    # The generated singleton method emits a one-time deprecation
+    # warning naming the replacement, then forwards all positional and
+    # keyword arguments plus any block to ``replacement``. Used for the
+    # ``decode`` / ``encode`` / ``engine*`` / ``with_engine`` /
+    # ``default_engine`` aliases that are scheduled for removal in v2.0.
+    #
+    # @api private
+    # @param name [Symbol] deprecated method name
+    # @param replacement [Symbol] current-API method to delegate to
+    # @return [Symbol] the defined method name
+    # @example
+    #   deprecate_alias :decode, :load
+    def deprecate_alias(name, replacement)
+      message = "MultiJson.#{name} is deprecated and will be removed in v2.0. Use MultiJson.#{replacement} instead."
+      define_singleton_method(name) do |*args, **kwargs, &block|
+        warn_deprecation_once(name, message)
+        public_send(replacement, *args, **kwargs, &block)
+      end
+    end
+
+    # Define a deprecated method whose body needs custom delegation
+    #
+    # Used for the ``default_options`` / ``default_options=`` pair
+    # whose body fans out to multiple replacement methods, and for the
+    # ``cached_options`` / ``reset_cached_options!`` no-op stubs that
+    # have no current-API counterpart at all. The block runs in its
+    # own lexical ``self``, which is the ``MultiJson`` module since
+    # every call site sits inside ``module MultiJson`` below.
+    #
+    # @api private
+    # @param name [Symbol] deprecated method name
+    # @param message [String] warning to emit on first call
+    # @yield body to evaluate after the warning
+    # @return [Symbol] the defined method name
+    # @example
+    #   deprecate_method(:cached_options, "...") { nil }
+    def deprecate_method(name, message, &body)
+      define_singleton_method(name) do |*args, **kwargs|
+        warn_deprecation_once(name, message)
+        body.call(*args, **kwargs)
+      end
+    end
+  end
+
+  deprecate_alias :decode, :load
+  deprecate_alias :encode, :dump
+  deprecate_alias :engine, :adapter
+  deprecate_alias :engine=, :adapter=
+  deprecate_alias :default_engine, :default_adapter
+  deprecate_alias :with_engine, :with_adapter
+
+  deprecate_method(
+    :default_options=,
+    "MultiJson.default_options setter is deprecated\n" \
+    "Use MultiJson.load_options and MultiJson.dump_options instead"
+  ) { |value| self.load_options = self.dump_options = value }
+
+  deprecate_method(
+    :default_options,
+    "MultiJson.default_options is deprecated\n" \
+    "Use MultiJson.load_options or MultiJson.dump_options instead"
+  ) { load_options }
+
+  %i[cached_options reset_cached_options!].each do |name|
+    deprecate_method(name, "MultiJson.#{name} method is deprecated and no longer used.") { nil }
+  end
+
+  private
+
+  # Instance-method delegate for the deprecated default_options setter
+  #
+  # @api private
+  # @deprecated Use {MultiJson.load_options=} and {MultiJson.dump_options=} instead
+  # @param value [Hash] options hash
+  # @return [Hash] the options hash
+  # @example
+  #   class Foo; include MultiJson; end
+  #   Foo.new.send(:default_options=, symbolize_keys: true)
+  def default_options=(value)
+    MultiJson.default_options = value
+  end
+
+  # Instance-method delegate for the deprecated default_options getter
+  #
+  # @api private
+  # @deprecated Use {MultiJson.load_options} or {MultiJson.dump_options} instead
+  # @return [Hash] the current load options
+  # @example
+  #   class Foo; include MultiJson; end
+  #   Foo.new.send(:default_options)
+  def default_options
+    MultiJson.default_options
+  end
+end

data/lib/multi_json/options.rb

@@ -1,39 +1,112 @@
+# frozen_string_literal: true
+
 module MultiJson
+  # Mixin providing configurable load/dump options
+  #
+  # Supports static hashes or dynamic callables (procs/lambdas).
+  # Extended by both MultiJson (global options) and Adapter classes.
+  #
+  # @api private
   module Options
+    # Steep needs an inline `#:` annotation here because `{}.freeze`
+    # would be inferred as `Hash[untyped, untyped]` and trip
+    # `UnannotatedEmptyCollection`. The annotation requires
+    # `Hash.new.freeze` (not the `{}.freeze` rubocop would prefer)
+    # because the `#:` cast only applies to method-call results.
+    EMPTY_OPTIONS = Hash.new.freeze #: options # rubocop:disable Style/EmptyLiteral
+
+    # Set options for load operations
+    #
+    # @api public
+    # @param options [Hash, Proc] options hash or callable
+    # @return [Hash, Proc] the options
+    # @example
+    #   MultiJson.load_options = {symbolize_keys: true}
     def load_options=(options)
       OptionsCache.reset
       @load_options = options
     end
 
+    # Set options for dump operations
+    #
+    # @api public
+    # @param options [Hash, Proc] options hash or callable
+    # @return [Hash, Proc] the options
+    # @example
+    #   MultiJson.dump_options = {pretty: true}
     def dump_options=(options)
       OptionsCache.reset
       @dump_options = options
     end
 
+    # Get options for load operations
+    #
+    # When `@load_options` is a callable (proc/lambda), it's invoked
+    # with `args` as positional arguments — typically the merged
+    # options hash from `Adapter.merged_load_options`. When it's a
+    # plain hash, `args` is ignored.
+    #
+    # @api public
+    # @param args [Array<Object>] forwarded to the callable, ignored otherwise
+    # @return [Hash] resolved options hash
+    # @example
+    #   MultiJson.load_options  #=> {}
     def load_options(*args)
-      defined?(@load_options) && get_options(@load_options, *args) || default_load_options
+      resolve_options(@load_options, *args) || default_load_options
     end
 
+    # Get options for dump operations
+    #
+    # @api public
+    # @param args [Array<Object>] forwarded to the callable, ignored otherwise
+    # @return [Hash] resolved options hash
+    # @example
+    #   MultiJson.dump_options  #=> {}
     def dump_options(*args)
-      defined?(@dump_options) && get_options(@dump_options, *args) || default_dump_options
+      resolve_options(@dump_options, *args) || default_dump_options
     end
 
+    # Get default load options
+    #
+    # @api private
+    # @return [Hash] frozen empty hash
     def default_load_options
-      @default_load_options ||= {}
+      Concurrency.synchronize(:default_options) { @default_load_options ||= EMPTY_OPTIONS }
     end
 
+    # Get default dump options
+    #
+    # @api private
+    # @return [Hash] frozen empty hash
     def default_dump_options
-      @default_dump_options ||= {}
+      Concurrency.synchronize(:default_options) { @default_dump_options ||= EMPTY_OPTIONS }
     end
 
-  private
+    private
 
-    def get_options(options, *args)
-      if options.respond_to?(:call) && options.arity
-        options.arity == 0 ? options[] : options[*args]
-      elsif options.respond_to?(:to_hash)
-        options.to_hash
+    # Resolves options from a hash or callable
+    #
+    # @api private
+    # @param options [Hash, Proc, nil] options configuration
+    # @param args [Array<Object>] arguments forwarded to a callable provider
+    # @return [Hash, nil] resolved options hash
+    def resolve_options(options, *args)
+      if options.respond_to?(:call)
+        # @type var options: options_proc
+        return invoke_callable(options, *args)
       end
+
+      options.to_hash if options.respond_to?(:to_hash)
+    end
+
+    # Invokes a callable options provider
+    #
+    # @api private
+    # @param callable [Proc] options provider
+    # @param args [Array<Object>] arguments forwarded when the callable is non-arity-zero
+    # @return [Hash] options returned by the callable
+    def invoke_callable(callable, *args)
+      callable.arity.zero? ? callable.call : callable.call(*args)
     end
   end
 end

data/lib/multi_json/options_cache/mutex_store.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module MultiJson
+  module OptionsCache
+    # Thread-safe cache store backed by a Hash guarded by a Mutex
+    #
+    # Used on MRI and TruffleRuby, where a runtime dependency on
+    # concurrent-ruby would be overkill: the GVL on MRI makes single
+    # lookups atomic, and locking on both reads and writes keeps the
+    # small perf cost predictable across engines without adding a
+    # runtime dependency.
+    #
+    # @api private
+    class Store
+      # Create a new cache store
+      #
+      # @api private
+      # @return [Store] new store instance
+      def initialize
+        @cache = {}
+        @mutex = Mutex.new
+      end
+
+      # Clear all cached entries
+      #
+      # Held under the mutex because TruffleRuby (which also uses this
+      # backend via the ruby-platform gem) has true parallelism: a
+      # concurrent ``fetch`` racing with ``Hash#clear`` could corrupt
+      # iteration in a way that MRI's GVL would otherwise prevent.
+      #
+      # @api private
+      # @return [void]
+      def reset
+        @mutex.synchronize { @cache.clear }
+      end
+
+      # Fetch a value from cache or compute it
+      #
+      # When called with a block, returns the cached value or computes a
+      # new one. When called without a block, returns the cached value or
+      # the supplied default if the key is missing. Nil cached values are
+      # preserved because ``Hash#fetch`` only falls through to the default
+      # block when the key is truly missing. The ``block_given?`` check
+      # is hoisted out of the mutex so the no-block read path runs the
+      # check once per call instead of once inside the critical section.
+      #
+      # @api private
+      # @param key [Object] cache key
+      # @param default [Object] value to return when key is missing and no
+      #   block is given
+      # @yield block to compute value if not cached
+      # @return [Object] cached, computed, or default value
+      def fetch(key, default = nil)
+        return @mutex.synchronize { @cache.fetch(key) { default } } unless block_given?
+
+        @mutex.synchronize do
+          @cache.fetch(key) do
+            @cache.shift if @cache.size >= OptionsCache.max_cache_size
+            @cache[key] = yield
+          end
+        end
+      end
+    end
+  end
+end

data/lib/multi_json/options_cache.rb

@@ -1,29 +1,86 @@
+# frozen_string_literal: true
+
 module MultiJson
+  # Thread-safe bounded cache for merged options hashes
+  #
+  # Caches are separated for load and dump operations. Each cache is
+  # bounded to prevent unbounded memory growth when options are
+  # generated dynamically. The ``Store`` backend is chosen at load time
+  # based on ``RUBY_ENGINE``: JRuby uses Concurrent::Map (shipped as a
+  # runtime dependency of the java-platform gem); MRI and TruffleRuby
+  # use a Hash guarded by a Mutex.
+  #
+  # @api private
   module OptionsCache
-    extend self
+    # Default bound on the number of cached entries per store. Applications
+    # that dynamically generate many distinct option hashes can raise this
+    # via {.max_cache_size=}.
+    DEFAULT_MAX_CACHE_SIZE = 1000
 
-    def reset
-      @dump_cache = {}
-      @load_cache = {}
-    end
+    class << self
+      # Get the dump options cache
+      #
+      # @api private
+      # @return [Store] dump cache store
+      attr_reader :dump
 
-    def fetch(type, key, &block)
-      cache = instance_variable_get("@#{type}_cache")
-      cache.key?(key) ? cache[key] : write(cache, key, &block)
-    end
+      # Get the load options cache
+      #
+      # @api private
+      # @return [Store] load cache store
+      attr_reader :load
 
-    private
+      # Maximum number of entries per cache store
+      #
+      # Applies to both the dump and load caches. Existing entries are
+      # left in place until normal eviction trims them below a lowered
+      # limit; call {.reset} if you need to evict immediately.
+      #
+      # @api public
+      # @return [Integer] current cache size limit
+      # @example
+      #   MultiJson::OptionsCache.max_cache_size = 5000
+      #   MultiJson::OptionsCache.max_cache_size  #=> 5000
+      attr_reader :max_cache_size
 
-    # Normally MultiJson is used with a few option sets for both dump/load
-    # methods. When options are generated dynamically though, every call would
-    # cause a cache miss and the cache would grow indefinitely. To prevent
-    # this, we just reset the cache every time the number of keys outgrows
-    # 1000.
-    MAX_CACHE_SIZE = 1000
+      # Set the maximum number of entries per cache store
+      #
+      # @api public
+      # @param value [Integer] positive entry cap
+      # @return [Integer] the validated value
+      # @raise [ArgumentError] when value is not a positive Integer
+      # @example
+      #   MultiJson::OptionsCache.max_cache_size = 5000
+      def max_cache_size=(value)
+        raise ArgumentError, "max_cache_size must be a positive Integer, got #{value.inspect}" unless Integer === value && value.positive? # rubocop:disable Style/CaseEquality
 
-    def write(cache, key)
-      cache.clear if cache.length >= MAX_CACHE_SIZE
-      cache[key] = yield
+        @max_cache_size = value
+      end
+
+      # Reset both caches
+      #
+      # @api private
+      # @return [void]
+      def reset
+        @dump = Store.new
+        @load = Store.new
+      end
     end
+
+    self.max_cache_size = DEFAULT_MAX_CACHE_SIZE
   end
 end
+
+module MultiJson
+  module OptionsCache
+    # Dynamic require path so MRI (mutex_store) and JRuby
+    # (concurrent_store) execute the same physical line, avoiding a
+    # dead-branch ``require_relative`` that would otherwise drop
+    # JRuby's line coverage below 100%.
+    BACKENDS = {"jruby" => "concurrent_store"}.freeze
+    private_constant :BACKENDS
+  end
+end
+
+require_relative "options_cache/#{MultiJson::OptionsCache.send(:const_get, :BACKENDS).fetch(RUBY_ENGINE, "mutex_store")}"
+MultiJson::OptionsCache.reset

data/lib/multi_json/parse_error.rb

@@ -1,17 +1,103 @@
+# frozen_string_literal: true
+
 module MultiJson
+  # Raised when JSON parsing fails
+  #
+  # Wraps the underlying adapter's parse error with the original input
+  # data, plus best-effort line and column extraction from the adapter's
+  # error message. Line/column are populated for adapters that include
+  # them in their messages (Oj, the json gem) and remain nil for
+  # adapters that don't (Yajl, fast_jsonparser).
+  #
+  # @api public
   class ParseError < StandardError
-    attr_reader :data, :cause
+    # Regex that matches the "line N[, ]column M" fragment inside an
+    # adapter error message. The separator between line and column is
+    # permissive — Oj emits ``"line 1, column 3"`` while the json gem
+    # emits ``"line 1 column 2"`` — so ``[,\s]+`` covers both. Column
+    # is optional so messages like ``"at line 5"`` still yield a line.
+    LOCATION_PATTERN = /line\s+(\d+)(?:[,\s]+column\s+(\d+))?/i
+    private_constant :LOCATION_PATTERN
+
+    # The input string that failed to parse
+    #
+    # @api public
+    # @return [String, nil] the original input data
+    # @example
+    #   error.data  #=> "{invalid json}"
+    attr_reader :data
+
+    # The 1-based line number reported by the adapter
+    #
+    # @api public
+    # @return [Integer, nil] line number, or nil if the adapter's message
+    #   did not include one
+    # @example
+    #   error.line  #=> 1
+    attr_reader :line
+
+    # The 1-based column reported by the adapter
+    #
+    # @api public
+    # @return [Integer, nil] column number, or nil if the adapter's message
+    #   did not include one
+    # @example
+    #   error.column  #=> 3
+    attr_reader :column
+
+    # Create a new ParseError
+    #
+    # @api public
+    # @param message [String, nil] error message
+    # @param data [String, nil] the input that failed to parse
+    # @param cause [Exception, nil] the original exception
+    # @return [ParseError] new error instance
+    # @example
+    #   ParseError.new("unexpected token at line 1 column 2", data: "{}")
+    def initialize(message = nil, data: nil, cause: nil)
+      super(message)
+      @data = data
+      match = location_match(message)
+      @line = match && Integer(match[1])
+      @column = match && match[2] && Integer(match[2])
+      set_backtrace(cause.backtrace) if cause
+    end
 
+    # Build a ParseError from an original exception
+    #
+    # @api public
+    # @param original_exception [Exception] the adapter's parse error
+    # @param data [String] the input that failed to parse
+    # @return [ParseError] new error with formatted message
+    # @example
+    #   ParseError.build(JSON::ParserError.new("..."), "{bad json}")
     def self.build(original_exception, data)
-      new(original_exception.message).tap do |exception|
-        exception.instance_eval do
-          @cause = original_exception
-          set_backtrace original_exception.backtrace
-          @data = data
-        end
-      end
+      new(original_exception.message, data: data, cause: original_exception)
+    end
+
+    private
+
+    # Match an adapter error message against the line/column pattern
+    #
+    # Adapter error messages sometimes embed bytes from the failing
+    # input (e.g., the json gem's ``"invalid byte sequence in UTF-8"``
+    # error). The pattern is pure ASCII so it's compatible with any
+    # encoding, but a UTF-8 string with invalid bytes still trips the
+    # regex engine — ``String#scrub`` replaces those bytes so the
+    # match can proceed. Strings in binary (ASCII-8BIT) or any valid
+    # encoding pass through scrub untouched.
+    #
+    # @api private
+    # @param message [String, nil] the adapter's error message
+    # @return [MatchData, nil] the regex match, or nil if no message or
+    #   no location fragment was found
+    def location_match(message)
+      return unless message
+
+      LOCATION_PATTERN.match(message.scrub)
     end
   end
 
-  DecodeError = LoadError = ParseError # Legacy support
+  # Legacy aliases for backward compatibility
+  DecodeError = LoadError = ParseError
 end

data/lib/multi_json/version.rb

@@ -1,17 +1,30 @@
+# frozen_string_literal: true
+
 module MultiJson
+  # Version information for MultiJson
+  #
+  # @api private
   class Version
+    # Major version number
     MAJOR = 1 unless defined? MultiJson::Version::MAJOR
-    MINOR = 15 unless defined? MultiJson::Version::MINOR
-    PATCH = 0 unless defined? MultiJson::Version::PATCH
+    # Minor version number
+    MINOR = 20 unless defined? MultiJson::Version::MINOR
+    # Patch version number
+    PATCH = 1 unless defined? MultiJson::Version::PATCH
+    # Pre-release version suffix
     PRE = nil unless defined? MultiJson::Version::PRE
 
     class << self
-      # @return [String]
+      # Return the version string
+      #
+      # @api private
+      # @return [String] version in semver format
       def to_s
-        [MAJOR, MINOR, PATCH, PRE].compact.join('.')
+        [MAJOR, MINOR, PATCH, PRE].compact.join(".")
       end
     end
   end
 
+  # Current version string in semver format
   VERSION = Version.to_s.freeze
 end