multi_json 1.19.1 → 1.21.1

data/lib/multi_json/deprecated.rb

@@ -0,0 +1,113 @@
+# 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
+    # ``load`` / ``dump`` / ``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 :load, :parse
+    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 :load, :parse
+  deprecate_alias :dump, :generate
+  deprecate_alias :decode, :parse
+  deprecate_alias :encode, :generate
+  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.parse_options and MultiJSON.generate_options instead"
+  ) { |value| self.parse_options = self.generate_options = value }
+
+  deprecate_method(
+    :default_options,
+    "MultiJSON.default_options is deprecated\n" \
+    "Use MultiJSON.parse_options or MultiJSON.generate_options instead"
+  ) { parse_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,64 +1,159 @@
-module MultiJson
-  # Mixin providing configurable load/dump options
+# frozen_string_literal: true
+
+module MultiJSON
+  # Mixin providing configurable parse/generate options
   #
   # Supports static hashes or dynamic callables (procs/lambdas).
-  # Extended by both MultiJson (global options) and Adapter classes.
+  # Extended by both MultiJSON (global options) and Adapter classes.
   #
   # @api private
   module Options
-    EMPTY_OPTIONS = {}.freeze
-    private_constant :EMPTY_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
+    # Set options for parse operations
     #
-    # @api private
+    # @api public
     # @param options [Hash, Proc] options hash or callable
     # @return [Hash, Proc] the options
-    def load_options=(options)
+    # @example
+    #   MultiJSON.parse_options = {symbolize_keys: true}
+    def parse_options=(options)
       OptionsCache.reset
-      @load_options = options
+      @parse_options = options
     end
 
-    # Set options for dump operations
+    # Set options for generate operations
     #
-    # @api private
+    # @api public
     # @param options [Hash, Proc] options hash or callable
     # @return [Hash, Proc] the options
-    def dump_options=(options)
+    # @example
+    #   MultiJSON.generate_options = {pretty: true}
+    def generate_options=(options)
       OptionsCache.reset
-      @dump_options = options
+      @generate_options = options
     end
 
-    # Get options for load operations
+    # Get options for parse operations
     #
-    # @api private
+    # When `@parse_options` is a callable (proc/lambda), it's invoked
+    # with `args` as positional arguments — typically the merged
+    # options hash from `Adapter.merged_parse_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.parse_options  #=> {}
+    def parse_options(*args)
+      resolve_options(@parse_options, *args) || default_parse_options
+    end
+
+    # Get options for generate operations
+    #
+    # @api public
+    # @param args [Array<Object>] forwarded to the callable, ignored otherwise
     # @return [Hash] resolved options hash
-    def load_options(...)
-      resolve_options(@load_options, ...) || default_load_options
+    # @example
+    #   MultiJSON.generate_options  #=> {}
+    def generate_options(*args)
+      resolve_options(@generate_options, *args) || default_generate_options
     end
 
-    # Get options for dump operations
+    # Get default parse options
     #
     # @api private
+    # @return [Hash] frozen empty hash
+    def default_parse_options
+      Concurrency.synchronize(:default_options) { @default_parse_options ||= EMPTY_OPTIONS }
+    end
+
+    # Get default generate options
+    #
+    # @api private
+    # @return [Hash] frozen empty hash
+    def default_generate_options
+      Concurrency.synchronize(:default_options) { @default_generate_options ||= EMPTY_OPTIONS }
+    end
+
+    # Set options for parse operations
+    #
+    # @api public
+    # @deprecated Use {#parse_options=} instead. Will be removed in v2.0.
+    # @param options [Hash, Proc] options hash or callable
+    # @return [Hash, Proc] the options
+    # @example
+    #   MultiJSON.load_options = {symbolize_keys: true}
+    def load_options=(options)
+      MultiJSON.warn_deprecation_once(:load_options=,
+        "MultiJSON.load_options= is deprecated and will be removed in v2.0. Use MultiJSON.parse_options= instead.")
+      self.parse_options = options
+    end
+
+    # Set options for generate operations
+    #
+    # @api public
+    # @deprecated Use {#generate_options=} instead. Will be removed in v2.0.
+    # @param options [Hash, Proc] options hash or callable
+    # @return [Hash, Proc] the options
+    # @example
+    #   MultiJSON.dump_options = {pretty: true}
+    def dump_options=(options)
+      MultiJSON.warn_deprecation_once(:dump_options=,
+        "MultiJSON.dump_options= is deprecated and will be removed in v2.0. Use MultiJSON.generate_options= instead.")
+      self.generate_options = options
+    end
+
+    # Get options for parse operations
+    #
+    # @api public
+    # @deprecated Use {#parse_options} instead. Will be removed in v2.0.
+    # @param args [Array<Object>] forwarded to the callable, ignored otherwise
+    # @return [Hash] resolved options hash
+    # @example
+    #   MultiJSON.load_options  #=> {}
+    def load_options(*args)
+      MultiJSON.warn_deprecation_once(:load_options,
+        "MultiJSON.load_options is deprecated and will be removed in v2.0. Use MultiJSON.parse_options instead.")
+      parse_options(*args)
+    end
+
+    # Get options for generate operations
+    #
+    # @api public
+    # @deprecated Use {#generate_options} instead. Will be removed in v2.0.
+    # @param args [Array<Object>] forwarded to the callable, ignored otherwise
     # @return [Hash] resolved options hash
-    def dump_options(...)
-      resolve_options(@dump_options, ...) || default_dump_options
+    # @example
+    #   MultiJSON.dump_options  #=> {}
+    def dump_options(*args)
+      MultiJSON.warn_deprecation_once(:dump_options,
+        "MultiJSON.dump_options is deprecated and will be removed in v2.0. Use MultiJSON.generate_options instead.")
+      generate_options(*args)
     end
 
-    # Get default load options
+    # Get default parse options
     #
     # @api private
+    # @deprecated Use {#default_parse_options} instead. Will be removed in v2.0.
     # @return [Hash] frozen empty hash
     def default_load_options
-      @default_load_options ||= EMPTY_OPTIONS
+      default_parse_options
     end
 
-    # Get default dump options
+    # Get default generate options
     #
     # @api private
+    # @deprecated Use {#default_generate_options} instead. Will be removed in v2.0.
     # @return [Hash] frozen empty hash
     def default_dump_options
-      @default_dump_options ||= EMPTY_OPTIONS
+      default_generate_options
     end
 
     private
@@ -67,9 +162,13 @@ module MultiJson
     #
     # @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, ...)
-      return invoke_callable(options, ...) if options.respond_to?(:call)
+    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
@@ -78,9 +177,10 @@ module MultiJson
     #
     # @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, ...)
-      callable.arity.zero? ? callable.call : callable.call(...)
+    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,74 +1,21 @@
-module MultiJson
-  # Thread-safe LRU-like cache for merged options hashes
+# 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.
+  # 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
-    # Maximum entries before oldest entry is evicted
-    MAX_CACHE_SIZE = 1000
-
-    # Thread-safe cache store using double-checked locking pattern
-    #
-    # @api private
-    class Store
-      # Sentinel value to detect cache misses (unique object identity)
-      NOT_FOUND = Object.new
-
-      # Create a new cache store
-      #
-      # @api private
-      # @return [Store] new store instance
-      def initialize
-        @cache = {}
-        @mutex = Mutex.new
-      end
-
-      # Clear all cached entries
-      #
-      # @api private
-      # @return [void]
-      def reset
-        @mutex.synchronize { @cache.clear }
-      end
-
-      # Fetch a value from cache or compute it
-      #
-      # @api private
-      # @param key [Object] cache key
-      # @param default [Object] default value if key not found
-      # @yield block to compute value if not cached
-      # @return [Object] cached or computed value
-      def fetch(key, default = nil)
-        # Fast path: check cache without lock (safe for reads)
-        value = @cache.fetch(key, NOT_FOUND)
-        return value unless value.equal?(NOT_FOUND)
-
-        # Slow path: acquire lock and compute value
-        @mutex.synchronize do
-          @cache.fetch(key) { block_given? ? store(key, yield) : default }
-        end
-      end
-
-      private
-
-      # Stores a value in the cache with LRU eviction
-      #
-      # @api private
-      # @param key [Object] cache key
-      # @param value [Object] value to store
-      # @return [Object] the stored value
-      def store(key, value)
-        # Double-check in case another thread computed while we waited
-        @cache.fetch(key) do
-          # Evict oldest entry if at capacity (Hash maintains insertion order)
-          @cache.shift if @cache.size >= MAX_CACHE_SIZE
-          @cache[key] = value
-        end
-      end
-    end
+    # 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
 
     class << self
       # Get the dump options cache
@@ -83,6 +30,33 @@ module MultiJson
       # @return [Store] load cache store
       attr_reader :load
 
+      # 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
+
+      # 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
+
+        @max_cache_size = value
+      end
+
       # Reset both caches
       #
       # @api private
@@ -93,6 +67,20 @@ module MultiJson
       end
     end
 
-    reset
+    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,10 +1,24 @@
-module MultiJson
+# frozen_string_literal: true
+
+module MultiJSON
   # Raised when JSON parsing fails
   #
-  # Wraps the underlying adapter's parse error with the original input data.
+  # 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
+    # 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
@@ -13,6 +27,24 @@ module MultiJson
     #   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
@@ -21,10 +53,13 @@ module MultiJson
     # @param cause [Exception, nil] the original exception
     # @return [ParseError] new error instance
     # @example
-    #   ParseError.new("unexpected token", data: "{invalid}", cause: err)
+    #   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
 
@@ -39,6 +74,28 @@ module MultiJson
     def self.build(original_exception, data)
       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
 
   # Legacy aliases for backward compatibility

data/lib/multi_json/version.rb

@@ -1,16 +1,18 @@
-module MultiJson
-  # Version information for MultiJson
+# frozen_string_literal: true
+
+module MultiJSON
+  # Version information for MultiJSON
   #
   # @api private
   class Version
     # Major version number
-    MAJOR = 1 unless defined? MultiJson::Version::MAJOR
+    MAJOR = 1 unless defined? MultiJSON::Version::MAJOR
     # Minor version number
-    MINOR = 19 unless defined? MultiJson::Version::MINOR
+    MINOR = 21 unless defined? MultiJSON::Version::MINOR
     # Patch version number
-    PATCH = 1 unless defined? MultiJson::Version::PATCH
+    PATCH = 1 unless defined? MultiJSON::Version::PATCH
     # Pre-release version suffix
-    PRE = nil unless defined? MultiJson::Version::PRE
+    PRE = nil unless defined? MultiJSON::Version::PRE
 
     class << self
       # Return the version string