nosj 0.4.0-aarch64-linux → 0.5.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd883bdfebc07e316c4baa1706cd9ba6b8036645a8cbd0b8b9b5a888c3a0e3c5
-  data.tar.gz: f73808429bfdf03043716ceb4b3d01a3536a4b6d2f1c092f15b54dff52ef9c82
+  metadata.gz: 8bd202a41866bf66ced093153a4a0ca1166ed3a2dc495eaa8189d0a6e6b58aa7
+  data.tar.gz: 8c7c12413a1bff0d9ff9d72d5629700e14a5c922fd1790ebe2ec46879be45d25
 SHA512:
-  metadata.gz: 7dab8b234f37fa22a4ab1a5f0bfb906df9ecb6d85ecba50f63e5634d309387ea0ce4302eda8e2280d182ae69d0067ee852d4b23773d1c1c4164c1b6ed708cadf
-  data.tar.gz: '0909f76cdcd4d49f015ee951d14f785312d91e6cc6ff61c18be8fe5c091f068c546f7a5f2d5a41cbce0db75de9fd4c20ddfbcca249906997f2c7a09fc8380f96'
+  metadata.gz: 045b0214d996b133b5c99ec958d5f929f12adf7e134671c9ff70895a4168d9a6a7ce78c261d6d8c5453b38af7363ded4a918b9d5fbb6c50dd8b06b15283de4af
+  data.tar.gz: d8717b79f4bddf22206fa248e57521282be0f197210683724adb8f831adf5a26581dd92e9d0192e3973070252f5acdc2968e6f8686ea5c916ebc5387a72602bc

data/CHANGELOG.md

@@ -1,3 +1,108 @@
+## [0.5.0] - 2026-09-25
+
+**json 3.0 compatibility.** nosj now matches the behavior of the json
+gem 3.0, and stays compatible with both the json 2.x and 3.0
+interfaces: `NOSJ.parse`, `NOSJ.generate`, and the rest of nosj's own
+API follow json 3.0 semantics, while the `nosj/json` drop-in follows
+whichever json gem your application has installed, 2.x or 3.0, down to
+its calling conventions and the documents it accepts. Upgrading json
+(or not) is your choice; nosj works with either.
+
+Behavior changes in nosj's own API, for input that was accepted
+before:
+
+- Duplicate object keys raise `NOSJ::ParserError` (positioned at the
+  object repeating the key, like json 3) in `parse`, `load_file`,
+  `valid?` (returns false), `minify`/`reformat`, and everything that
+  materializes values. `allow_duplicate_key: true` restores the old
+  behavior: the last value wins (in `minify`, repeated keys pass
+  through).
+- Lone UTF-16 surrogates such as `"\udc00"` raise `NOSJ::ParserError`
+  everywhere, trailing ones included (they used to decode to raw
+  WTF-8 bytes, and `minify` re-escaped them).
+- `generate` raises `NOSJ::GeneratorError` for keys that render alike
+  (`{"a" => 1, :a => 2}`, `{1 => 1, "1" => 2}`), with json 3's exact
+  message; `allow_duplicate_key: true` emits them as before. Hashes
+  whose keys are all of one kind are never checked. The Rails encoder
+  is unchanged.
+- `stats` still describes such documents rather than refusing them.
+- Unknown options raise ArgumentError with json 3's message
+  (`unknown keyword: foo`) in every entry point, instead of being
+  ignored. json options nosj does not implement (`object_class`,
+  `array_class`, `decimal_class`, `on_load`, `create_additions`,
+  `allow_comments`, `allow_control_characters`,
+  `allow_invalid_escape`, `sort_keys`, `as_json`) raise unless falsy;
+  `on_load` and the newer ones used to be silently ignored.
+  `escape_slash` is gone, as in json 3: use `script_safe`.
+  `quirks_mode` is no longer accepted. `stats` takes only the options
+  it documents (`max_nesting`, `allow_nan`, `allow_trailing_comma`).
+
+The `nosj/json` drop-in follows the installed json gem:
+
+- With json 3.0, `JSON.parse` takes keyword options only, `JSON.dump`
+  uses json 3's defaults (nesting capped at 100), and whatever json 3
+  refuses (`quirks_mode`, `escape_slash`, `create_additions`, unknown
+  options, positional option hashes) raises exactly as json 3 raises.
+- With json 2.x, everything behaves as before, including json 2's
+  acceptance of duplicate keys, lone surrogates, and comments, and
+  its handling of keys that render alike.
+- Whenever the fast path refuses a call, the installed gem runs it
+  again and decides: exceptions are now the gem's own (message,
+  `json_path`, `invalid_object`) rather than nosj's messages re-raised
+  as JSON classes. The second pass happens on failures only, and a
+  `generate` run twice this way calls `to_json` again on the objects
+  visited before the refusal.
+- Fixed: `JSON.dump` raised NameError (`_dump_default_options`) with
+  json older than 2.11, which includes the json bundled with Ruby 3.3
+  and 3.4.
+- Fixed: `JSON.generate` (and `pretty_generate`, `dump`) with both
+  `ascii_only` and `script_safe` raised ArgumentError; that combination,
+  which nosj does not implement, now goes to the gem.
+
+## [0.4.1] - 2026-09-25
+
+- Fixed a crash in `NOSJ.generate`: an object whose `to_json` or
+  `to_s` shrank the array being generated (for example with
+  `Array#clear`) made the generator read freed memory, usually a
+  segfault. The array length is now re-read for every element, like
+  the json gem, so elements a callback appends are emitted too.
+- Fixed memory corruption in `NOSJ.splice`: a replacement value whose
+  `to_json` modified the source string, deduplicated a frozen String
+  subclass (`-str`), or removed entries from the edits hash could make
+  splice read freed memory, copying unrelated heap bytes into the
+  result or crashing. All values are now generated before the source
+  is read.
+- Fixed `NOSJ.lazy` and `NOSJ.each_line` reading freed memory when the
+  source is a frozen String subclass (such as
+  `ActiveSupport::SafeBuffer`) or a frozen string carrying instance
+  variables, and it is deduplicated with `-str` while the lazy
+  document is alive or between lines: Ruby swaps such a string's
+  buffer, and the old one kept being read (wrong values, or a crash).
+- Fixed a memory leak in `NOSJ.generate` and `NOSJ.write_file`: an
+  exception raised by user code the generator calls bypassed its
+  cleanup and leaked its output buffer (megabytes per call after large
+  documents). Affected: a raising `respond_to?` or
+  `respond_to_missing?`, a raising `to_s` on an encoding-conversion
+  error, a raising autoload of `JSON::Fragment` (strict and Rails
+  modes), and a raising `Errno` constructor for a failed write. The
+  exception still propagates unchanged.
+- Fixed: after a `NoMemoryError` in the middle of a parse (or
+  `minify`/`reformat`), the next call on that thread aborted the whole
+  process. Per-thread parser state is now recovered instead.
+- `NOSJ::Lazy` nodes now take part in generational GC: holding many
+  nodes no longer slows down every minor GC (200,000 live nodes: 2.9 ms
+  per minor GC before, 0.1 ms now), and they are freed immediately
+  when collected.
+- Fixed: lazy documents opened with `allow_trailing_comma: true` or
+  `allow_nan: true` could not be walked. `size`, `keys`, `each`, and
+  any lookup that missed or stepped over a trailing comma or a `NaN`
+  raised `NOSJ::ParserError`, even though `value` worked.
+- `NOSJ.at_pointer`, `NOSJ.at_pointers`, and `NOSJ.at_pointer_file`
+  now honor `allow_nan` and `allow_trailing_comma` while resolving the
+  pointer, not only when materializing the matched value.
+- Updated the nosj crate to 0.2.2.
+- Updated dependencies, Magnus bumped to 0.9.0.
+
 ## [0.4.0] - 2026-09-05
 
 - Ractors: on Ruby 4.0+, `NOSJ.parse`, `NOSJ.generate`, and every

data/README.md

@@ -65,6 +65,10 @@ through nosj:
 require "nosj/json"
 ```
 
+It works with json 2.x and 3.0 alike and follows whichever your app
+has installed: its calling conventions, its defaults, and the documents
+it accepts.
+
 In a Bundler app (Rails included) that can live entirely in the
 Gemfile you can do this:
 
@@ -108,9 +112,11 @@ The `json` gem API, on the `NOSJ` module:
 
 ```ruby
 NOSJ.parse(src, symbolize_names: true)   # also: freeze, max_nesting,
-                                         # allow_nan, allow_trailing_comma
+                                         # allow_nan, allow_trailing_comma,
+                                         # allow_duplicate_key
 NOSJ.generate(obj)                       # indent, space, object_nl, ...,
-NOSJ.pretty_generate(obj)                # ascii_only, script_safe, strict
+NOSJ.pretty_generate(obj)                # ascii_only, script_safe, strict,
+                                         # allow_duplicate_key
 ```
 
 ### Lazy documents
@@ -151,7 +157,8 @@ Example: an early field resolves in ~0.35µs where `JSON.parse(json).dig(...)`
 costs ~980µs on the same document—three orders of magnitude. A field
 at the far end of a 570 KB document costs ~71µs, still 13× faster
 than parse-then-dig. Misses return nil; matched subtrees materialize
-with the same options as `parse` (`symbolize_names:`, `freeze:`).
+with the same options as `parse` (`symbolize_names:`, `freeze:`), and
+`allow_nan:`/`allow_trailing_comma:` govern the walk to them too.
 
 ### Files API
 
@@ -188,10 +195,11 @@ NOSJ.reformat_file("big.json")           # straight off a memory map
 ```
 
 Output is exactly `generate(parse(json))`—canonical number spellings,
-normalized escapes, same formatting options—except duplicate keys pass
-through (a reformatter must not silently drop data) and lone-surrogate
-strings re-escape instead of raising. Acceptance options apply too:
-`minify(src, allow_trailing_comma: true)` normalizes the commas away.
+normalized escapes, same formatting options—and it accepts exactly what
+`parse` does. Acceptance options apply too:
+`minify(src, allow_trailing_comma: true)` normalizes the commas away,
+and under `allow_duplicate_key: true` repeated keys pass through (a
+reformatter must not silently drop data).
 
 ### Byte-splicing edits and JSON Patch
 
@@ -402,19 +410,28 @@ Reproduce with `rake bench` (the parity-gated comparison, after a PGO retrain—
 
 ## Switching from the json gem
 
-You mostly don't have to do anything. Some differences:
-
-- The legacy object-deserialization options (`create_additions`,
-  `object_class`, `array_class`, `decimal_class`) raise ArgumentError;
-  the `nosj/json` drop-in falls back to the original gem for them.
-- Behaviors the `json` gem itself deprecates (JS comments, raw invalid
-  UTF-8) follow the strict semantics instead.
+You mostly don't have to do anything. `NOSJ.*` follows json 3.0,
+whichever json your app runs; the `nosj/json` drop-in follows the
+installed one, 2.x or 3.0. Some differences:
+
+- json 3.0 semantics: duplicate keys, lone surrogates, JS comments,
+  and invalid UTF-8 are errors (`allow_duplicate_key: true` restores
+  last-key-wins), keys that render alike raise in `generate`, and
+  unknown options raise ArgumentError. With json 2.x installed, the
+  drop-in keeps json 2's leniency: when nosj refuses a call, the
+  installed gem runs it and has the last word.
+- The json options nosj doesn't implement (`create_additions`,
+  `object_class`, `array_class`, `decimal_class`, `on_load`,
+  `allow_comments`, `allow_control_characters`,
+  `allow_invalid_escape`, `sort_keys`, `as_json`) raise ArgumentError
+  unless falsy; the drop-in passes them to the original gem.
 - Unlike `Array#dig`, negative indices in `NOSJ.dig` return nil (JSON
   Pointer has no equivalent).
 - Parse errors raise `NOSJ::ParserError` (`NOSJ::NestingError` past
   `max_nesting`, like the gem); messages use byte offsets rather than
   the gem's phrasing, and the exception carries `#line`, `#column`,
-  and a caret `#snippet`.
+  and a caret `#snippet`. Through the drop-in, exceptions are the
+  installed gem's own (message, `json_path`, `invalid_object`).
 
 Everything else—including the gem's exact float formatting, which is
 not the shortest-round-trip form most libraries emit—matches

data/lib/nosj/json.rb

@@ -12,12 +12,18 @@
 # Entry points built on JSON.parse (JSON.load, JSON.parse!,
 # JSON.load_file, JSON.unsafe_load) pick up the fast path automatically
 # and keep their exact legacy behavior when they need unsupported options
-# (JSON.load's create_additions default always takes the fallback).
+# (json 2's JSON.load passes create_additions, so it always takes the
+# fallback).
 #
-# Exceptions from the fast path are re-raised as the JSON classes
-# (JSON::ParserError, JSON::GeneratorError, JSON::NestingError), so
-# existing rescue clauses keep working. Parse error MESSAGES are
-# NOSJ's (byte offsets rather than the gem's phrasing).
+# The drop-in follows whichever json is installed, 2.x or 3.x: its
+# calling conventions (json 3's keyword-only parse, its dump defaults)
+# and its semantics. NOSJ implements json 3's (duplicate keys and lone
+# surrogates are errors), so whenever the fast path refuses a call, the
+# original gem runs it again and has the last word: json 2 accepts what
+# it always accepted, and every exception is the gem's own, message,
+# json_path and invalid_object included. That second pass happens on
+# failures only; a generate run twice this way calls to_json on the
+# objects visited before the refusal twice.
 #
 # Not rerouted: obj.to_json (core extensions drive the gem's generator
 # directly), and objects with a custom to_json inside a rerouted
@@ -30,15 +36,26 @@ module NOSJ
   # Implementation detail of `require "nosj/json"`.
   # @private
   module JSONDropIn
-    # quirks_mode rides the fast path because NOSJ.parse is always
-    # quirks-mode (top-level scalars parse) and ignores the key; Rails
-    # 7.x passes it from ActiveSupport::JSON.decode.
+    # json 3 made parse's options keyword-only, fixed dump's defaults and
+    # raises for options json 2 ignored or aliased.
+    JSON3 = ::JSON::VERSION.to_i >= 3
+
     PARSE_OPTS = %i[symbolize_names freeze max_nesting allow_nan
-      allow_trailing_comma quirks_mode].freeze
+      allow_trailing_comma allow_duplicate_key].freeze
+    # json 2 ignores quirks_mode, which Rails 7.x passes from
+    # ActiveSupport::JSON.decode, so its fast path takes the key and
+    # drops it (NOSJ.parse always parses top-level scalars, and refuses
+    # unknown keys). json 3 raises for it, so there it reaches the gem
+    # like any other unknown option.
+    QUIRKS_MODE = :quirks_mode
+    JSON2_PARSE_OPTS = (PARSE_OPTS + [QUIRKS_MODE]).freeze
     GENERATE_OPTS = %i[indent space space_before object_nl array_nl
-      max_nesting allow_nan ascii_only script_safe
-      escape_slash strict depth
-      buffer_initial_length].freeze
+      max_nesting allow_nan ascii_only script_safe strict depth
+      buffer_initial_length allow_duplicate_key].freeze
+    JSON3_DUMP_DEFAULTS = {allow_nan: true}.freeze
+    # json 2.10 and older accept only strict: in dump's options hash,
+    # through this private helper; later versions merge any option.
+    DUMP_MERGES_OPTIONS = !::JSON.respond_to?(:merge_dump_options, true)
 
     module_function
 
@@ -52,6 +69,13 @@ module NOSJ
       true
     end
 
+    # Generate options the fast path handles: supported keys, minus the
+    # one combination NOSJ refuses (ascii_only with script_safe, which
+    # json supports).
+    def generate_supported?(opts)
+      supported?(opts, GENERATE_OPTS) && !(opts && opts[:ascii_only] && opts[:script_safe])
+    end
+
     def parse(source, opts)
       # NOSJ.parse is deliberately strict about encodings (json-3.0
       # semantics), but the drop-in must match the installed gem, which
@@ -61,30 +85,60 @@ module NOSJ
       # (copy-on-write bytes), and the validity scan is memoized
       # coderange the parse would compute anyway. Anything else
       # non-UTF-8 (UTF-16, ...) belongs to gem json, which transcodes.
+      input = source
       if source.is_a?(String)
         case source.encoding
         when Encoding::UTF_8, Encoding::US_ASCII
         # the fast path as-is
         when Encoding::BINARY
           utf8 = source.dup.force_encoding(Encoding::UTF_8)
-          source = utf8 if utf8.valid_encoding?
+          input = utf8 if utf8.valid_encoding?
         else
-          return ::JSON.nosj_original_parse(source, **(opts || {}))
+          return original_parse(source, opts)
         end
       end
-      NOSJ.parse(source, opts)
-    rescue NOSJ::NestingError => e
-      raise ::JSON::NestingError, e.message
-    rescue NOSJ::ParserError => e
-      raise ::JSON::ParserError, e.message
+      NOSJ.parse(input, opts)
+    rescue NOSJ::ParserError, NOSJ::NestingError
+      original_parse(source, opts)
+    end
+
+    # json 2's options without quirks_mode (see QUIRKS_MODE), allocating
+    # nothing for Rails' lone `quirks_mode: true`.
+    def without_quirks_mode(opts)
+      return opts unless opts&.key?(QUIRKS_MODE)
+      if opts.size == 1
+        nil
+      else
+        opts.except(QUIRKS_MODE)
+      end
+    end
+
+    # The installed gem's parse. json 3 takes keywords only; json 2's
+    # positional options hash receives them just the same.
+    def original_parse(source, opts)
+      ::JSON.nosj_original_parse(source, **(opts || {}))
     end
 
     def generate(obj, opts, pretty)
       pretty ? NOSJ.pretty_generate(obj, opts) : NOSJ.generate(obj, opts)
-    rescue NOSJ::NestingError => e
-      raise ::JSON::NestingError, e.message
-    rescue NOSJ::GeneratorError => e
-      raise ::JSON::GeneratorError, e.message
+    rescue NOSJ::GeneratorError, NOSJ::NestingError
+      if pretty
+        ::JSON.nosj_original_pretty_generate(obj, opts)
+      else
+        ::JSON.nosj_original_generate(obj, opts)
+      end
+    end
+
+    # The options JSON.dump generates with before the caller's own: fixed
+    # in json 3; json 2 reads its user-settable dump_default_options,
+    # through the internal reader 2.11 added when it deprecated the
+    # public one. Which one is decided here, once.
+    if JSON3
+      def dump_defaults = JSON3_DUMP_DEFAULTS
+    elsif ::JSON.respond_to?(:_dump_default_options)
+      def dump_defaults = ::JSON._dump_default_options
+    else
+      def dump_defaults = ::JSON.dump_default_options
     end
   end
 end
@@ -101,16 +155,26 @@ module JSON
       alias_method :nosj_original_pretty_generate, :pretty_generate
       alias_method :nosj_original_dump, :dump
 
-      def parse(source, opts = nil)
-        if NOSJ::JSONDropIn.supported?(opts, NOSJ::JSONDropIn::PARSE_OPTS)
-          NOSJ::JSONDropIn.parse(source, opts)
-        else
-          nosj_original_parse(source, opts)
+      if NOSJ::JSONDropIn::JSON3
+        def parse(source, **opts)
+          if NOSJ::JSONDropIn.supported?(opts, NOSJ::JSONDropIn::PARSE_OPTS)
+            NOSJ::JSONDropIn.parse(source, opts)
+          else
+            nosj_original_parse(source, **opts)
+          end
+        end
+      else
+        def parse(source, opts = nil)
+          if NOSJ::JSONDropIn.supported?(opts, NOSJ::JSONDropIn::JSON2_PARSE_OPTS)
+            NOSJ::JSONDropIn.parse(source, NOSJ::JSONDropIn.without_quirks_mode(opts))
+          else
+            nosj_original_parse(source, opts)
+          end
         end
       end
 
       def generate(obj, opts = nil)
-        if NOSJ::JSONDropIn.supported?(opts, NOSJ::JSONDropIn::GENERATE_OPTS)
+        if NOSJ::JSONDropIn.generate_supported?(opts)
           NOSJ::JSONDropIn.generate(obj, opts, false)
         else
           nosj_original_generate(obj, opts)
@@ -118,7 +182,7 @@ module JSON
       end
 
       def pretty_generate(obj, opts = nil)
-        if NOSJ::JSONDropIn.supported?(opts, NOSJ::JSONDropIn::GENERATE_OPTS)
+        if NOSJ::JSONDropIn.generate_supported?(opts)
           NOSJ::JSONDropIn.generate(obj, opts, true)
         else
           nosj_original_pretty_generate(obj, opts)
@@ -127,17 +191,19 @@ module JSON
 
       def dump(obj, an_io = nil, limit = nil, kwargs = nil)
         # Fast path for the common shapes, dump(obj) and dump(obj, opts
-        # hash), mirroring gem json: dump defaults merged under the
-        # user's options, NestingError surfaced as ArgumentError. IO and
-        # limit arguments take gem json's own dump.
-        if limit.nil? && kwargs.nil? && (an_io.nil? || an_io.instance_of?(Hash))
-          opts = _dump_default_options
+        # hash): the installed gem's dump defaults merged under the
+        # caller's options. IO and limit arguments, and anything the
+        # fast path refuses, take gem json's own dump, which also turns
+        # json 2's NestingError into its ArgumentError.
+        if limit.nil? && kwargs.nil? &&
+            (an_io.nil? || NOSJ::JSONDropIn::DUMP_MERGES_OPTIONS && an_io.instance_of?(Hash))
+          opts = NOSJ::JSONDropIn.dump_defaults
           opts = opts.merge(an_io) if an_io
-          if NOSJ::JSONDropIn.supported?(opts, NOSJ::JSONDropIn::GENERATE_OPTS)
+          if NOSJ::JSONDropIn.generate_supported?(opts)
             begin
-              return NOSJ::JSONDropIn.generate(obj, opts, false)
-            rescue ::JSON::NestingError
-              raise ArgumentError, "exceed depth limit"
+              return NOSJ.generate(obj, opts)
+            rescue NOSJ::GeneratorError, NOSJ::NestingError
+              # the gem's own dump below runs it again and decides
             end
           end
         end

data/lib/nosj/version.rb

@@ -2,5 +2,5 @@
 
 module NOSJ
   # The gem version.
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/lib/nosj.rb

@@ -86,10 +86,13 @@ module NOSJ
   # Parses a JSON document, JSON.parse-compatible: same values, same
   # option names, same behavior, byte-for-byte.
   #
-  # The +json+ gem's legacy object-deserialization options
-  # (+object_class+, +array_class+, +decimal_class+,
-  # +create_additions+) are deliberately unsupported and raise
-  # ArgumentError.
+  # Options follow json 3: an unknown key raises ArgumentError
+  # (<code>unknown keyword: foo</code>). The json options nosj does not
+  # implement (+object_class+, +array_class+, +decimal_class+,
+  # +on_load+, +create_additions+, +allow_comments+,
+  # +allow_control_characters+, +allow_invalid_escape+) raise
+  # ArgumentError unless falsy, since their falsy default is nosj's
+  # behavior.
   #
   # @example
   #   NOSJ.parse('{"a":[1,true]}')                      #=> {"a" => [1, true]}
@@ -98,12 +101,14 @@ module NOSJ
   # @param source [String] the JSON document (UTF-8 or US-ASCII)
   # @param opts [Hash, nil] +symbolize_names+, +freeze+, +max_nesting+
   #   (Integer or +false+ for unlimited), +allow_nan+,
-  #   +allow_trailing_comma+
+  #   +allow_trailing_comma+, +allow_duplicate_key+ (json 3 semantics:
+  #   a repeated key raises unless this is true, then the last one wins)
   # @return [Object] the parsed value tree
-  # @raise [ParserError] when the document is malformed or not UTF-8;
-  #   carries the failure position ({ParserError#line} and friends)
+  # @raise [ParserError] when the document is malformed, repeats a key,
+  #   holds a lone surrogate (+"\udc00"+), or is not UTF-8; carries the
+  #   failure position ({ParserError#line} and friends)
   # @raise [NestingError] when nesting exceeds +max_nesting+
-  # @raise [ArgumentError] for unsupported options
+  # @raise [ArgumentError] for unknown or unsupported options
   def self.parse(source, opts = nil)
     parse_native(source, opts)
   end
@@ -119,12 +124,18 @@ module NOSJ
   #   @param obj [Object] the value tree to serialize
   #   @param opts [Hash, nil] +indent+, +space+, +space_before+,
   #     +object_nl+, +array_nl+, +max_nesting+ (Integer or +false+),
-  #     +allow_nan+, +ascii_only+, +script_safe+ (alias +escape_slash+),
-  #     +strict+, +depth+, +buffer_initial_length+
+  #     +allow_nan+, +ascii_only+, +script_safe+, +strict+, +depth+,
+  #     +buffer_initial_length+, +allow_duplicate_key+ (json 3
+  #     semantics: keys that render alike, like <code>"a"</code> and
+  #     <code>:a</code>, raise unless true). As in json 3, an unknown
+  #     key raises (+escape_slash+ is gone: use +script_safe+), and the
+  #     unimplemented +sort_keys+ and +as_json+ raise unless falsy.
   #   @return [String] the JSON document
   #   @raise [GeneratorError] for non-finite floats without +allow_nan+,
-  #     unsupported objects under +strict+, or broken string encodings
+  #     unsupported objects under +strict+, keys that render alike, or
+  #     broken string encodings
   #   @raise [NestingError] when nesting exceeds +max_nesting+
+  #   @raise [ArgumentError] for unknown or unsupported options
 
   # Generates human-readable JSON, JSON.pretty_generate-compatible
   # (two-space indent, newlines between elements). Options override the
@@ -156,7 +167,7 @@ module NOSJ
   # @param source [String] the JSON document
   # @param opts [Hash, nil] same options as {.parse}
   # @return [Boolean]
-  # @raise [ArgumentError] for unsupported options
+  # @raise [ArgumentError] for unknown or unsupported options
   def self.valid?(source, opts = nil)
     valid_native(source, opts)
   end
@@ -205,7 +216,8 @@ module NOSJ
 
   # Partial parsing by JSON Pointer (with the standard +~0+/+~1+
   # escapes). The matched subtree materializes under the same options
-  # as {.parse}.
+  # as {.parse}; +allow_nan+ and +allow_trailing_comma+ also govern the
+  # walk to it.
   #
   # @example
   #   NOSJ.at_pointer(json, "/users/3/name")  #=> "grace" or nil
@@ -322,18 +334,19 @@ module NOSJ
   # Minifies a document without building any Ruby values: the parser's
   # events pipe straight into the emission kernels, SIMD in and SIMD
   # out. Output is exactly what <code>generate(parse(json))</code>
-  # would produce, except duplicate object keys pass through instead of
-  # being collapsed (a reformatter must not silently drop data).
-  # Numbers come out in the canonical spelling (+1.50+ becomes +1.5+)
-  # and string escapes are normalized.
+  # would produce, and it accepts exactly what {.parse} accepts; under
+  # +allow_duplicate_key+, repeated keys pass through instead of being
+  # collapsed (a reformatter must not silently drop data). Numbers come
+  # out in the canonical spelling (+1.50+ becomes +1.5+) and string
+  # escapes are normalized.
   #
   # @example
   #   NOSJ.minify(%({ "a": [1, 2],\n  "b": "x" }))  #=> '{"a":[1,2],"b":"x"}'
   #
   # @param json [String] the document (UTF-8 or US-ASCII)
   # @param opts [Hash, nil] acceptance options (+allow_nan+,
-  #   +allow_trailing_comma+, +max_nesting+); trailing commas are
-  #   normalized away when accepted
+  #   +allow_trailing_comma+, +allow_duplicate_key+, +max_nesting+);
+  #   trailing commas are normalized away when accepted
   # @return [String] the minified document
   # @raise [ParserError] when the document is malformed
   # @raise [NestingError] past +max_nesting+
@@ -357,8 +370,7 @@ module NOSJ
   # @return [String] the reformatted document
   # @raise [ParserError] when the document is malformed
   # @raise [NestingError] past +max_nesting+
-  # @raise [GeneratorError] when +ascii_only+ meets a lone-surrogate
-  #   string it cannot represent
+  # @raise [GeneratorError] for a non-finite float without +allow_nan+
   def self.reformat(json, opts = nil)
     if opts&.key?(:pretty)
       pretty = opts[:pretty]
@@ -597,7 +609,9 @@ module NOSJ
   #
   # @param source [String] the JSON document (UTF-8 or US-ASCII)
   # @param opts [Hash, nil] +max_nesting+, +allow_nan+,
-  #   +allow_trailing_comma+ (acceptance options only)
+  #   +allow_trailing_comma+ (acceptance options only). Being a
+  #   diagnostic, stats also describes documents {.parse} would refuse
+  #   for a repeated key or a lone surrogate.
   # @return [Hash] the statistics described above
   # @raise [ParserError] when the document is malformed or not UTF-8
   def self.stats(source, opts = nil)

data/sig/nosj.rbs

@@ -14,9 +14,10 @@ module NOSJ
   # Options arrive as a positional Hash (the JSON gem's own calling
   # convention; an explicit **kwargs would allocate per call), nil when
   # omitted. Parse: symbolize_names, freeze, max_nesting, allow_nan,
-  # allow_trailing_comma. Generate: indent, space, space_before,
-  # object_nl, array_nl, max_nesting, allow_nan, ascii_only,
-  # script_safe/escape_slash, strict, depth, buffer_initial_length.
+  # allow_trailing_comma, allow_duplicate_key. Generate: indent, space,
+  # space_before, object_nl, array_nl, max_nesting, allow_nan,
+  # ascii_only, script_safe, strict, depth, buffer_initial_length,
+  # allow_duplicate_key. Unknown keys raise ArgumentError (json 3).
   type opts = Hash[Symbol, untyped]?
 
   # One NOSJ.dig path element (negative Integer indices resolve to nil).

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nosj
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: aarch64-linux
 authors:
 - Yaroslav Markin
@@ -66,7 +66,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: 3.3.11
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: An extremely fast JSON parser and generator for Ruby, written in Rust and
   SIMD-accelerated on every platform.