nosj 0.2.0-x86_64-linux → 0.3.1-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 46cefa7803d25d779048e2c450ea1c5b5daa0c42508277432ef99df7918c783c
-  data.tar.gz: b11bcb71b9334785acbc7c3f1c48570f212e77646cb3c613db7cc76261895250
+  metadata.gz: a03b7acd00b05ca48947bf80319648b4042b3e62d50094d4d075b35eaedccec5
+  data.tar.gz: 4fcf70e0bb3e57b5ce15449363d3ab14d02721ffbbe724cc95bb15a1e48da2f6
 SHA512:
-  metadata.gz: 1789804de8bff93994f515aba7d8fe5ac0f527e865bb8d917c8ed7d9a2cd08e7a3cddb2b0194653697eb62aafa466820c97b01c15a9afde9530a4f8b98bdedd5
-  data.tar.gz: 5aab59746b4856fb2afb505d18da3c4d9b2c3f0f02e115c402a17e94c5669b911443899cbf0958771606ae95789764ced92b091a1d5917cb186c620570811978
+  metadata.gz: 177ccd493e943f35b96da5ac6aa1cef5ff72f757194d97130e34ed0c7141aae99f06b0d5bf6d141ff3222f8fb50e6f26c68ad93890b618c6526da384dd6e293c
+  data.tar.gz: 706499dbb44d2f09209735702e9d7e0421279a0fd7d71626878d545669dc34c9267d4fb11de51d07b16f75940d73511fae934365abb4cffca82bef6e53f974ce

data/CHANGELOG.md

@@ -1,3 +1,115 @@
+## [0.3.1] - 2026-07-17
+
+- Fixed: `NOSJ.minify` / `NOSJ.reformat` produced unparseable output
+  for a float that overflows to Infinity—a huge-exponent literal like
+  `1e999`, or a ~300-digit integer with an exponent (such literals
+  parse to Infinity even in strict mode, matching the `json` gem).
+  The pipe emitted a bare `Infinity` token; it now raises the same
+  `GeneratorError` that `generate` would
+  (`"Infinity not allowed in JSON"`). With `allow_nan: true` the
+  literal still passes through as `Infinity`. Found by fuzzing.
+- Fixed (second manifestation, also found by fuzzing): the same
+  unparseable output could appear with the overflowing literal hidden
+  behind a duplicate object key. Because the reformat pipe
+  deliberately preserves duplicate-key entries, it now refuses such
+  documents with the same `GeneratorError` even though
+  `generate(parse(x))` succeeds there (last-key-wins parsing discards
+  the shadowed value)—a documented divergence.
+- Differential fuzzing for the native extension (`ext/nosj/fuzz`):
+  three cargo-fuzz targets—reformat, NDJSON framing, and
+  byte-splicing/JSON Patch—each drive the real entry points on an
+  embedded Ruby VM and compare every input against pure-Ruby
+  reference implementations, with committed seed corpora and a weekly
+  CI workflow (`fuzz.yml`).
+
+## [0.3.0] - 2026-07-17
+
+- Reformat without parsing. `NOSJ.minify(json, opts)` and
+  `NOSJ.reformat(json, opts)` (plus `NOSJ.reformat_file`) pipe the
+  parser's events straight into the emission kernels: zero Ruby
+  objects are allocated for the document, and output is exactly
+  `generate(parse(json))`—canonical numbers, normalized escapes, the
+  full set of `generate` formatting and escape options, with
+  `pretty: true` as a `pretty_generate` shorthand—except duplicate
+  object keys pass through and lone-surrogate string values re-escape
+  as `\uXXXX` instead of raising (the output must always reparse).
+  Acceptance options apply per `parse` (`allow_trailing_comma`
+  normalizes the commas away). Measured on the 631 KB twitter.json:
+  409µs, 3.4× faster than `NOSJ.generate(NOSJ.parse(x))`, 3.9× faster
+  than gem json's cycle, 5.3× faster than Oj's, and 1.4× the cost of
+  `NOSJ.valid?`.
+- Byte-splicing edits and JSON Patch. `NOSJ.splice(json, pointer =>
+  value, ...)` replaces values directly in the text: every target
+  resolves in one forward pass and the result is rebuilt copying all
+  bytes outside the target spans untouched (formatting, key order, and
+  number spellings elsewhere survive exactly). Measured on
+  twitter.json: 10× faster than parse-mutate-generate for a late
+  field, 51× for an early one. Missing targets raise KeyError,
+  overlapping targets ArgumentError. `NOSJ.patch(json, ops)` applies
+  RFC 6902 JSON Patch (add/remove/replace/move/copy/test, String or
+  Symbol op keys) to the raw string the same way, with structural ops
+  walking only the parent container's span; application failures raise
+  the new `NOSJ::PatchError`, malformed patch documents ArgumentError.
+  `NOSJ.merge_patch(json, patch)` applies RFC 7386 JSON Merge Patch
+  (semantic form). Inserted values are byte-identical to
+  `NOSJ.generate` and accept its options; the RFC 6902 appendix-A
+  suite and the full RFC 7386 test table are in the specs.
+- NDJSON / JSON Lines. `NOSJ.each_line(source, opts)` yields one
+  parsed value per line (Enumerator without a block, so
+  `.first(10)`/`.lazy` walk only what they consume), skipping blank
+  lines and enforcing one value per line; a malformed line raises the
+  rich `ParserError` whose `#line` is the physical line number in the
+  stream. `NOSJ.generate_lines(values, opts)` emits one compact
+  newline-terminated document per element in a single buffer pass
+  (measured 4.1× faster than the map-generate-join idiom on twitter
+  statuses; `each_line` is 1.6× faster than line-split +
+  `JSON.parse`), rejecting formatting options that would break line
+  framing. File forms: `NOSJ.each_line_file` streams over a read-only
+  memory map, `NOSJ.write_lines` generates straight to disk and
+  returns the byte count. Parse options apply per line; pass a frozen
+  string to `each_line` for zero-copy iteration.
+- `NOSJ.stats(source, opts)` / `NOSJ.stats_file(path, opts)`: document
+  statistics from one counting pass through the null-sink machinery,
+  answering "what is this 40 MB blob" without building any Ruby values
+  for the document (measured ~1.3× faster than a full parse). Reports
+  `byte_size`, `root` kind, `max_depth`, value counts by type, key
+  totals, a key histogram sorted by count, largest container sizes,
+  and string byte totals. Nesting is unlimited by default (pass
+  `max_nesting` to enforce a limit); `allow_nan` and
+  `allow_trailing_comma` are honored; malformed documents raise the
+  rich `ParserError`. The file form memory-maps, so the document never
+  enters Ruby at all.
+- Rich parse errors. Parse failures now raise `NOSJ::ParserError`
+  (previously a bare `RuntimeError`) carrying the failure position,
+  computed only when a parse fails: `#byte_offset`, 1-based `#line`,
+  character-based `#column`, and a caret `#snippet` showing the
+  offending line (windowed when the line is long, as minified JSON
+  usually is). Positions are absolute within the document you passed,
+  including through partial parsing (`dig`, `at_pointer`, batches),
+  lazy documents, and the file APIs. `#detailed_message` appends the
+  snippet, so unrescued errors print it. Failures with no position
+  (encoding refusals) leave the accessors nil. Exceeding `max_nesting`
+  during parsing now raises `NOSJ::NestingError`, matching the gem's
+  class (generation already did); rescues of the old `RuntimeError`
+  need updating to `NOSJ::ParserError`/`NOSJ::Error`.
+- Rails mode: `require "nosj/rails"` accelerates a Rails application
+  in both directions. It installs a nosj-backed ActiveSupport JSON
+  encoder, so `obj.to_json`, `render json:`, and `ActiveSupport::JSON.encode` walk the object tree natively—values recurse through `as_json` exactly
+  like ActiveSupport's own encoder. It also loads the `nosj/json` drop-in, so
+  `ActiveSupport::JSON.decode` and JSON request-body parsing take the
+  fast path (including on Rails 7.x, whose `quirks_mode` option the
+  drop-in now accepts; the drop-in also accepts valid-UTF-8 BINARY
+  strings now, which is what Rack delivers request bodies as). The
+  HTML-safety escaping is fused into the SIMD string-emission kernels,
+  so escaped output costs the same single pass as unescaped. Measured
+  against stock ActiveSupport encoding: ×1.7 on small documents up to
+  ×5.2 on large trees and ×14 on HTML-heavy content
+  (`rake bench:rails`). In a Rails Gemfile:
+  `gem "nosj", require: "nosj/rails"`.
+- `JSON::Fragment` values now splice their pre-rendered JSON
+  everywhere the `json` gem does: in default mode, under `strict:
+  true`, and through the Rails encoder.
+
 ## [0.2.0] - 2026-07-16
 
 - File APIs. `NOSJ.load_file(path, opts)` parses a file directly

data/README.md

@@ -13,11 +13,14 @@ faster than Yajl—[see Benchmarks](#benchmarks).
 - It has **lazy documents**: `NOSJ.lazy` wraps a document and parses a value only when you touch it—repeated access costs nanoseconds, and everything you never read is never parsed.
 - It has a **partial parsing mode**: JSON Pointer lookups that pull single values out of big documents in microseconds, skipping everything else.
 - It has **file APIs**: parse, generate, dig, and lazy-wrap files directly—no throwaway file-sized Ruby String, and the partial modes memory-map the file so unread pages never even leave the disk.
+- It does **byte-splicing edits**: `NOSJ.splice` changes a field inside a passing payload 10–51× faster than parse-mutate-generate, and RFC 6902 JSON Patch / RFC 7386 merge patch apply straight to the raw string.
+- It is **great to debug with**: parse errors carry line, column, and a caret snippet pointing at the break, and `NOSJ.stats` X-rays a mystery blob (depth, value counts, key histogram) faster than parsing it.
+- It accelerates a **Rails** application in both encoding and decoding.
 - It comes **precompiled** (platform gems built with per-platform optimizations,
 nothing to compile on install).
 - Otherwise, same API and option names as gem json.
 
-**And there's more**: validate documents without building a single Ruby object, resolve whole batches of paths in one pass, and accelerate an entire application with a one-line drop-in.
+**And there's more**: validate documents without building a single Ruby object, minify and pretty-print without parsing, resolve whole batches of paths in one pass, stream NDJSON / JSON Lines in both directions, and accelerate an entire application with a one-line drop-in.
 
 - [Requirements](#requirements)
 - [Getting started](#getting-started)
@@ -26,6 +29,7 @@ nothing to compile on install).
 - [Switching from the json gem](#switching-from-the-json-gem)
 - [How it works](#how-it-works)
 - [Development](#development)
+- [Acknowledgements](#acknowledgements)
 - [License](#license)
 
 ## Requirements
@@ -50,6 +54,8 @@ NOSJ.generate({"a" => [1, true]})  #=> '{"a":[1,true]}'
 
 That's it—if you know the `json` gem, you already know `nosj`.
 
+### gem json compatibility
+
 Want the speedup without touching your code? One line reroutes
 `JSON.parse`, `JSON.generate`, `JSON.pretty_generate`, and `JSON.dump`
 through nosj:
@@ -65,18 +71,39 @@ Gemfile you can do this:
 gem "nosj", require: "nosj/json"
 ```
 
-Options nosj supports take the fast path; anything exotic
-(`create_additions`, `object_class`, `JSON::State`, procs, IO
-arguments) falls back to the original implementation, so `JSON.load`,
-`JSON.parse!`, and `JSON.load_file` keep their exact behavior.
-Exceptions re-raise as the JSON classes, so your rescue clauses keep
-working. Measured through the patch: parse 1.11×, generate 1.05× over
-the original gem. (A MultiJson adapter ships too:
-`require "nosj/multi_json"`, then `MultiJson.use NOSJ::MultiJsonAdapter`.)
+A MultiJson adapter ships too: 
+
+```ruby
+require "nosj/multi_json"
+```
+
+And then `MultiJson.use NOSJ::MultiJsonAdapter`.
+
+### Ruby on Rails
+
+In a Rails app, use this for "Rails mode":
+
+```ruby
+gem "nosj", require: "nosj/rails"
+```
+
+That installs a nosj-backed ActiveSupport JSON encoder, so `obj.to_json`, `render json:`, and `ActiveSupport::JSON.encode` walk the object tree natively:
+values that aren't JSON-native recurse through `as_json` exactly like
+ActiveSupport's own encoder, non-finite floats encode as `null`, and
+HTML-safety escaping (`escape_html_entities_in_json`) behaves
+identically—verified differentially against ActiveSupport's encoder.
+It loads the drop-in too, so `ActiveSupport::JSON.decode` and JSON
+request-body parsing ride the fast path. 
+
+Measured against ActiveSupport's own encoder: ×1.9 on small documents
+up to ×5.2 on large trees and ×14 on HTML-heavy content—see
+[Benchmarks → Rails mode](#rails-mode).
 
 ## What's in the box
 
-**The `json` gem API**, on the `NOSJ` module:
+### json API
+
+The `json` gem API, on the `NOSJ` module:
 
 ```ruby
 NOSJ.parse(src, symbolize_names: true)   # also: freeze, max_nesting,
@@ -85,7 +112,9 @@ NOSJ.generate(obj)                       # indent, space, object_nl, ...,
 NOSJ.pretty_generate(obj)                # ascii_only, script_safe, strict
 ```
 
-**Lazy documents.** `NOSJ.lazy` wraps a document in a lazy view: read
+### Lazy documents
+
+`NOSJ.lazy` wraps a document in a lazy view: read
 a field and only that path is parsed—containers stay lazy, scalars
 arrive as plain Ruby values, and repeated reads are cached:
 
@@ -101,8 +130,9 @@ Pass a frozen string and creating the view is practically free—
 nanoseconds, even on a megabyte document. Malformed content raises
 when it is first read, not at wrap time.
 
+### Partial parsing
 
-**Partial parsing.** Pull values out of a document without
+Pull values out of a document without
 materializing the rest—skipped content is stepped over at SIMD block
 speed, so a lookup costs what it skips, not what the document weighs:
 
@@ -122,7 +152,9 @@ 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:`).
 
-**Files.** Every mode has a file-native form, so a document never
+### Files API
+
+Every mode has a file-native form, so a document never
 round-trips through a throwaway Ruby String:
 
 ```ruby
@@ -138,10 +170,89 @@ read are never loaded from disk. Missing files raise the usual
 `Errno` exceptions. Measured numbers live in
 [Benchmarks → File APIs](#file-apis).
 
-**Validation without parsing.** `NOSJ.valid?` runs the full
-parser—tokenizers, string decode, number validation—into a null sink
-and allocates no Ruby objects at all. It is 2-4× faster than
-`NOSJ.parse`, which already leads every parser above:
+### Reformat without parsing
+
+`NOSJ.minify` and `NOSJ.reformat` pipe the parser's events straight
+into the emission kernels: **zero Ruby objects** are built for the
+document (the specs assert it), SIMD in and SIMD out. Minifying the
+631 KB twitter.json takes 409µs—3.4× faster than a
+`generate(parse(x))` round-trip, 3.9× faster than gem json's cycle,
+and only 1.4× the cost of `valid?`:
+
+```ruby
+NOSJ.minify(json)                        # compact
+NOSJ.reformat(json, pretty: true)        # pretty_generate layout
+NOSJ.reformat(json, ascii_only: true)    # escape-transcode, no parse
+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.
+
+### Byte-splicing edits and JSON Patch
+
+Change a field in a passing payload without the parse → mutate →
+generate cycle: `NOSJ.splice` skips to the target spans (one pass for
+the whole batch) and rebuilds the string around them—every byte
+outside the targets is copied untouched, so formatting, key order,
+and number spellings survive exactly. On twitter.json this is
+**10×–51× faster** than parse-mutate-generate (129µs for a late
+field, 26µs for an early one, vs ~1.3ms):
+
+```ruby
+NOSJ.splice(json, "/config/timeout" => 30)
+NOSJ.splice(json, "/a" => 1, "/b/c" => [true])   # batch, one pass
+```
+
+On top of the same machinery: **RFC 6902 JSON Patch** applied to the
+raw string (`add`, `remove`, `replace`, `move`, `copy`, `test`—the
+whole appendix-A suite is in the specs), and **RFC 7386 JSON Merge
+Patch**:
+
+```ruby
+NOSJ.patch(json, [
+  {"op" => "test", "path" => "/a", "value" => 1},
+  {"op" => "replace", "path" => "/a", "value" => 2},
+  {"op" => "add", "path" => "/list/-", "value" => "x"}
+])
+NOSJ.merge_patch(json, {"config" => {"legacy" => nil, "timeout" => 30}})
+```
+
+Missing splice targets raise `KeyError` (use `patch` `add` to
+insert); failed patches raise `NOSJ::PatchError`; inserted values are
+byte-identical to `NOSJ.generate`'s output.
+
+### NDJSON / JSON Lines
+
+Logs, data pipelines, LLM batch files—one JSON document per line.
+`NOSJ.each_line` streams values out (1.6× faster than the
+line-split-and-`JSON.parse` idiom on twitter statuses), and
+`NOSJ.generate_lines` builds the whole stream in one buffer pass
+(4.1× faster than map-generate-join):
+
+```ruby
+NOSJ.each_line(log) { |event| ingest(event) }   # or an Enumerator:
+NOSJ.each_line(log).first(10)                   # walks only 10 lines
+
+NOSJ.generate_lines(events)          #=> %({"a":1}\n{"b":2}\n...)
+NOSJ.each_line_file("events.ndjson") { |e| }    # over a memory map
+NOSJ.write_lines("out.ndjson", events)          # straight to disk
+```
+
+Blank lines are skipped, one value per line is enforced, and a
+malformed line raises a [rich `ParserError`](#rich-parse-errors) whose
+`#line` is the physical line in the stream. Parse options apply per
+line—`NOSJ.each_line(log, freeze: true)` yields Ractor-shareable
+values.
+
+### Validation without parsing
+
+`NOSJ.valid?` runs the full parser—tokenizers, string decode, 
+number validation—into a null sink and allocates no Ruby objects
+at all. It is 2-4× faster than `NOSJ.parse`:
 
 ```ruby
 NOSJ.valid?('{"a":1}')                #=> true
@@ -149,6 +260,46 @@ NOSJ.valid?('{"a":}')                 #=> false
 NOSJ.valid?(src, max_nesting: false)  # same options as parse
 ```
 
+### Document statistics
+
+`NOSJ.stats` answers "what is this 40 MB blob": one counting pass 
+through the same null-sink machinery—no Ruby value is built for 
+the document, and it costs _less_ than a parse (~1.3× faster on `twitter.json`):
+
+```ruby
+s = NOSJ.stats(blob)          # or NOSJ.stats_file("huge.json")
+s[:byte_size]                 #=> 631514
+s[:root]                      #=> :object
+s[:max_depth]                 #=> 10
+s[:values]                    #=> {total: 13914, objects: 1264, arrays: 1050,
+                              #    strings: 4754, integers: 2108, ...}
+s[:keys]                      #=> {total: 13345, unique: 94}
+s[:key_histogram].first(3)    #=> [["id", 447], ["id_str", 447], ["urls", 364]]
+s[:containers]                #=> {max_object_entries: 40, max_array_length: 100}
+s[:strings]                   #=> {bytes: 200716, max_bytes: 463}
+```
+
+Nesting is unlimited by default (a deep blob is exactly what a
+diagnostic should describe); malformed documents raise the usual rich
+`ParserError`.
+
+### Rich parse errors
+
+A failed parse raises `NOSJ::ParserError`
+carrying where the document broke—`#byte_offset`, `#line`, `#column`,
+and a caret `#snippet`—computed only when a parse fails, so success
+pays nothing. Positions stay absolute through partial parsing, lazy
+documents, and the file APIs; unrescued errors print the snippet:
+
+```ruby
+NOSJ.parse(%({\n  "a": 1,\n  "b": }))
+# NOSJ::ParserError: unexpected character at byte 19
+#   e.line     #=> 3
+#   e.column   #=> 8
+#   e.snippet  #=>   "b": }
+#                         ^
+```
+
 ## Benchmarks
 
 Every installed JSON gem, benchmark-ips: AWS EC2 c7a.2xlarge (AMD EPYC 9R14, Zen 4), Ruby 4.0.6 + YJIT, json 2.21.1, Oj 3.17.4, RapidJSON 0.4.0, FastJsonparser 0.6.0, Yajl 1.4.3, PGO build, 2026-07-16. `×N` = times slower than nosj. 
@@ -209,6 +360,27 @@ Silicon dev box, Ruby 4.0.6 + YJIT, PGO build, 2026-07-16):
 too much for an honest multiplier; what it saves is the intermediate
 file-sized Ruby String.
 
+### Rails mode
+
+`ActiveSupport::JSON.encode` with the nosj encoder installed, against
+stock ActiveSupport (Apple Silicon dev box, Ruby 4.0.6 + YJIT,
+activesupport 8.1, medians of 5 interleaved per-process rounds,
+outputs verified byte-identical first, 2026-07-17;
+`rake bench:rails`):
+
+| workload | nosj (i/s) | vs ActiveSupport |
+|---|---:|---|
+| twitter tree (570 KB) | 4.5k | ×5.2 |
+| 100-record index (with timestamps) | 33.7k | ×1.7 |
+| HTML-heavy user content | 177.7k | ×14.2 |
+| Time/Date/BigDecimal hash | 1.1M | ×3.0 |
+| small API hash | 4.2M | ×1.9 |
+| small hash `to_json` | 4.1M | ×1.9 |
+
+The HTML-safety escaping that dominates stock encodes of
+user-generated content is fused into the SIMD string-emission kernels
+here: escaped output costs the same single pass as unescaped.
+
 Reproduce with `rake bench` (the parity-gated comparison, after a PGO retrain—the shipping configuration) or `rake bench:ips` (the multi-gem shoot-out).
 
 ## Switching from the json gem
@@ -222,8 +394,10 @@ You mostly don't have to do anything. Some differences:
   UTF-8) follow the strict semantics instead.
 - Unlike `Array#dig`, negative indices in `NOSJ.dig` return nil (JSON
   Pointer has no equivalent).
-- Parse error *messages* use byte offsets rather than the gem's
-  phrasing (classes match).
+- 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`.
 
 Everything else—including the gem's exact float formatting, which is
 not the shortest-round-trip form most libraries emit—matches
@@ -260,6 +434,33 @@ bundle exec rake bench:fast             # the sweep without retraining
 bundle exec rake "bench:ips[twitter]"   # multi-gem shoot-out (benchmark-ips); no args = full corpus
 ```
 
+The native layer is differentially fuzzed on an embedded VM
+(reformat pipe, NDJSON framing, splice/patch span arithmetic against
+pure-Ruby reference implementations)—see
+[ext/nosj/fuzz/README.md](ext/nosj/fuzz/README.md).
+
+## Acknowledgements
+
+Thanks to [Jean Boussier](https://github.com/byroot), [Florian Frank](https://github.com/flori), [Hiroshi Shibata](https://github.com/hsbt), [Nobuyoshi Nakada](https://github.com/nobu), [Étienne Barrié](https://github.com/etiennebarrie), and the other authors and maintainers of the [json gem](https://github.com/ruby/json)—for their work on the gem itself, for optimization ideas, and for some of the JSON documents in the benchmark corpus.
+
+Thanks to [Mat Sadler](https://github.com/matsadler) for [magnus](https://github.com/matsadler/magnus).
+
+Thanks to the authors of the projects credited in [NOTICE](NOTICE) and the
+crate's NOTICE: [fpconv](https://github.com/night-shift/fpconv) and
+Florian Loitsch's Grisu2,
+[fast_float](https://github.com/fastfloat/fast_float) and
+[fast_double_parser](https://github.com/lemire/fast_double_parser)
+(Daniel Lemire et al.),
+[simdjson](https://github.com/simdjson/simdjson) (Daniel Lemire, Geoff
+Langdale, and contributors), and the architectural lineage of
+[yyjson](https://github.com/ibireme/yyjson),
+[simd-json](https://github.com/simd-lite/simd-json), and
+[sonic-rs](https://github.com/cloudwego/sonic-rs).
+
+## Assisted by
+
+Claude Fable 5, Claude Opus 4.8.
+
 ## License
 
 MIT. The underlying Rust crate is `MIT AND BSL-1.0 AND Apache-2.0`; its

data/lib/nosj/json.rb

@@ -6,7 +6,7 @@
 #
 # reroutes JSON.parse, JSON.generate, JSON.pretty_generate and JSON.dump
 # through NOSJ whenever the requested options fall within NOSJ's
-# supported set, and falls back to the original json implementation for
+# supported set, and falls back to gem json's own implementation for
 # everything else (create_additions, object_class/array_class,
 # decimal_class, on_load procs, JSON::State instances, IO arguments).
 # Entry points built on JSON.parse (JSON.load, JSON.parse!,
@@ -30,8 +30,11 @@ 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.
     PARSE_OPTS = %i[symbolize_names freeze max_nesting allow_nan
-      allow_trailing_comma].freeze
+      allow_trailing_comma 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
@@ -41,7 +44,7 @@ module NOSJ
 
     # The fast path handles nil or a plain Hash whose every key NOSJ
     # implements; anything else (JSON::State, exotic options, string
-    # keys) belongs to the original implementation.
+    # keys) belongs to gem json.
     def supported?(opts, allowed)
       return true if opts.nil?
       return false unless opts.instance_of?(Hash)
@@ -50,8 +53,29 @@ module NOSJ
     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
+      # accepts more. BINARY strings holding valid UTF-8 are the big
+      # real-world case: Rack delivers request bodies as BINARY, so
+      # Rails JSON params come through here. Retagging a dup is cheap
+      # (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.
+      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?
+        else
+          return ::JSON.nosj_original_parse(source, **(opts || {}))
+        end
+      end
       NOSJ.parse(source, opts)
-    rescue RuntimeError => e
+    rescue NOSJ::NestingError => e
+      raise ::JSON::NestingError, e.message
+    rescue NOSJ::ParserError => e
       raise ::JSON::ParserError, e.message
     end
 
@@ -103,9 +127,9 @@ 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 the gem: dump defaults merged under the
+        # hash), mirroring gem json: dump defaults merged under the
         # user's options, NestingError surfaced as ArgumentError. IO and
-        # limit arguments take the original implementation.
+        # 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
           opts = opts.merge(an_io) if an_io

data/lib/nosj/multi_json.rb

@@ -36,7 +36,7 @@ module NOSJ
     # @raise [JSON::ParserError] when the document is malformed
     def load(string, options = {})
       ::NOSJ.parse(string, options[:symbolize_names] ? SYMBOLIZE : nil)
-    rescue RuntimeError => e
+    rescue ::NOSJ::ParserError, ::NOSJ::NestingError => e
       raise ParseError, e.message
     end
 

data/lib/nosj/rails.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+# Rails mode: `require "nosj/rails"` accelerates a Rails application in
+# both directions.
+#
+# - It installs {NOSJ::RailsEncoder} as ActiveSupport's JSON encoder
+#   (the official +ActiveSupport::JSON::Encoding.json_encoder+ seam, the
+#   same one Oj's Rails mode uses). That captures every encode a Rails
+#   app performs through +obj.to_json+, +render json:+, and
+#   +ActiveSupport::JSON.encode+: the object tree is walked natively,
+#   values that are not JSON-native recurse through +as_json+ exactly
+#   like ActiveSupport's own encoder, and non-finite floats encode as
+#   +null+ (+Float#as_json+ parity).
+# - It loads the `nosj/json` drop-in, so +JSON.parse+ (and with it
+#   +ActiveSupport::JSON.decode+ and JSON request-body parsing) takes
+#   the fast path.
+#
+# In a Rails Gemfile:
+#
+#   gem "nosj", require: "nosj/rails"
+#
+# +JSON::Fragment+ values splice their pre-rendered JSON, like current
+# ActiveSupport. On older ActiveSupport (before its encoder learned
+# about fragments) stock encoding dumps the fragment's instance
+# variables instead; there this encoder deliberately diverges in favor
+# of real splicing.
+
+require "nosj/json"
+require "active_support"
+require "active_support/json"
+
+module NOSJ
+  # ActiveSupport JSON encoder backed by nosj: the interface of
+  # ActiveSupport's +JSONGemEncoder+ (accepts the options hash, encodes
+  # one value), with the tree walk, generation, AND the HTML/JS-safety
+  # escape pass running natively (a byte scan instead of ActiveSupport's
+  # Ruby regex post-pass), honoring +escape_html_entities_in_json+ (and,
+  # where present, +escape_js_separators_in_json+ and the per-call
+  # +escape:+ / +escape_html_entities:+ options).
+  class RailsEncoder
+    # The escape_js_separators_in_json knob is newer than the Rails
+    # versions we support; its presence is fixed at load time (only its
+    # value can change at runtime). Absent, ActiveSupport always
+    # escapes the JS separators.
+    HAS_JS_SEPARATORS_KNOB =
+      ActiveSupport::JSON::Encoding.respond_to?(:escape_js_separators_in_json)
+    private_constant :HAS_JS_SEPARATORS_KNOB
+
+    attr_reader :options
+
+    def initialize(options = nil)
+      @options = options || {}
+    end
+
+    def encode(value)
+      value = value.as_json(@options.dup) unless @options.empty?
+      if @options.fetch(:escape, true)
+        escape_html = @options.fetch(:escape_html_entities) do
+          ActiveSupport::JSON::Encoding.escape_html_entities_in_json
+        end
+        NOSJ.generate_rails_native(value, !!escape_html, escape_js_separators?)
+      else
+        NOSJ.generate_rails_native(value, false, false)
+      end
+    end
+
+    private
+
+    def escape_js_separators?
+      !HAS_JS_SEPARATORS_KNOB ||
+        ActiveSupport::JSON::Encoding.escape_js_separators_in_json
+    end
+  end
+
+  ActiveSupport::JSON::Encoding.json_encoder = RailsEncoder
+end

data/lib/nosj/version.rb

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

data/lib/nosj.rb

@@ -26,15 +26,58 @@ module NOSJ
   # Base class for nosj errors.
   class Error < StandardError; end
 
+  # Raised when a document cannot be parsed. Carries the failure
+  # position, computed once when the parse fails (successful parses
+  # never pay for it): {#byte_offset}, 1-based {#line}, character-based
+  # {#column}, and a caret {#snippet} pointing at the offending spot.
+  # Positions are absolute within the document you passed, including
+  # through partial parsing ({NOSJ.dig}, {NOSJ.at_pointer}, lazy
+  # documents) and the file APIs. All four are +nil+ for failures
+  # without a position (encoding refusals).
+  #
+  # @example
+  #   NOSJ.parse(%({\n  "a": 1,\n  "b": }))
+  #   # => NOSJ::ParserError, with
+  #   #    e.line     #=> 3
+  #   #    e.column   #=> 8
+  #   #    e.snippet  #=> "  \"b\": }\n       ^"
+  class ParserError < Error
+    # @return [Integer, nil] byte offset of the failure in the source
+    attr_reader :byte_offset
+    # @return [Integer, nil] 1-based line of the failure
+    attr_reader :line
+    # @return [Integer, nil] 1-based character (not byte) column within
+    #   {#line}
+    attr_reader :column
+    # @return [String, nil] the offending line (windowed when long)
+    #   with a caret line underneath
+    attr_reader :snippet
+
+    # The default message plus {#snippet}: Ruby prints
+    # +detailed_message+ when an exception reaches the top level, so an
+    # unrescued parse error shows where the document broke.
+    def detailed_message(highlight: false, **opts)
+      base = super
+      snippet ? "#{base}\n#{snippet}" : base
+    end
+  end
+
   # Raised when a value cannot be generated (non-finite floats without
   # +allow_nan+, unsupported objects under +strict+, broken encodings).
   # Message-compatible with +JSON::GeneratorError+.
   class GeneratorError < Error; end
 
-  # Raised when generation exceeds +max_nesting+. Message-compatible
-  # with +JSON::NestingError+.
+  # Raised when parsing or generation exceeds +max_nesting+.
+  # Message-compatible with +JSON::NestingError+.
   class NestingError < Error; end
 
+  # Raised when an RFC 6902 patch cannot be applied: a +test+ operation
+  # failed, a target or source path does not exist, an array index is
+  # out of range, or a +move+ targets its own child. Structurally
+  # malformed patch documents (not an op Hash, unknown op, missing
+  # fields) raise ArgumentError instead.
+  class PatchError < Error; end
+
   PRETTY_GENERATE_OPTS = {
     indent: "  ", space: " ", object_nl: "\n", array_nl: "\n"
   }.freeze
@@ -57,7 +100,9 @@ module NOSJ
   #   (Integer or +false+ for unlimited), +allow_nan+,
   #   +allow_trailing_comma+
   # @return [Object] the parsed value tree
-  # @raise [RuntimeError] when the document is malformed or not UTF-8
+  # @raise [ParserError] when the document is malformed or not UTF-8;
+  #   carries the failure position ({ParserError#line} and friends)
+  # @raise [NestingError] when nesting exceeds +max_nesting+
   # @raise [ArgumentError] for unsupported options
   def self.parse(source, opts = nil)
     parse_native(source, opts)
@@ -204,7 +249,7 @@ module NOSJ
   # @param opts [Hash, nil] the same options as {.parse}
   # @return [Object] the parsed value tree
   # @raise [SystemCallError] +Errno::ENOENT+ and friends, like File.read
-  # @raise [RuntimeError] when the document is malformed or not UTF-8
+  # @raise [ParserError] when the document is malformed or not UTF-8
   def self.load_file(path, opts = nil)
     load_file_native(path, opts)
   end
@@ -240,7 +285,7 @@ module NOSJ
   # @param opts [Hash, nil] {.parse} options applied on materialization
   # @return [NOSJ::Lazy, Object]
   # @raise [SystemCallError] +Errno::ENOENT+ and friends
-  # @raise [RuntimeError] when the file is not UTF-8 or the root is malformed
+  # @raise [ParserError] when the file is not UTF-8 or the root is malformed
   def self.load_lazy_file(path, opts = nil)
     load_lazy_file_native(path, opts)
   end
@@ -273,4 +318,305 @@ module NOSJ
   def self.dig_file(path, *path_elements)
     dig_file_native(path, path_elements)
   end
+
+  # 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.
+  #
+  # @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
+  # @return [String] the minified document
+  # @raise [ParserError] when the document is malformed
+  # @raise [NestingError] past +max_nesting+
+  def self.minify(json, opts = nil)
+    reformat_native(json, opts)
+  end
+
+  # Reformats a document without building any Ruby values: {.minify}'s
+  # pipe with formatting. <code>pretty: true</code> is a shorthand for
+  # {.pretty_generate}'s layout; the individual {.generate} formatting
+  # and escape options (+indent+, +space+, +object_nl+, +ascii_only+,
+  # +script_safe+, ...) compose with it and win over it.
+  #
+  # @example
+  #   NOSJ.reformat(json, pretty: true)
+  #   NOSJ.reformat(json, ascii_only: true)   # escape-transcode, compact
+  #
+  # @param json [String] the document (UTF-8 or US-ASCII)
+  # @param opts [Hash, nil] +pretty+, {.generate} formatting/escape
+  #   options, and {.minify}'s acceptance options
+  # @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
+  def self.reformat(json, opts = nil)
+    if opts&.key?(:pretty)
+      pretty = opts[:pretty]
+      opts = opts.except(:pretty)
+      opts = PRETTY_GENERATE_OPTS.merge(opts) if pretty
+    end
+    reformat_native(json, opts)
+  end
+
+  # {.reformat} against a file: the pipe runs over a read-only memory
+  # map, so the input document never becomes a Ruby String; only the
+  # result does.
+  #
+  # @example
+  #   compact = NOSJ.reformat_file("big.json")            # minify
+  #   pretty  = NOSJ.reformat_file("big.json", pretty: true)
+  #
+  # @param path [String] the file to reformat (UTF-8)
+  # @param opts [Hash, nil] same options as {.reformat}
+  # @return [String] the reformatted document
+  # @raise [SystemCallError] +Errno::ENOENT+ and friends
+  # @raise [ParserError] when the file is malformed or not UTF-8
+  def self.reformat_file(path, opts = nil)
+    if opts&.key?(:pretty)
+      pretty = opts[:pretty]
+      opts = opts.except(:pretty)
+      opts = PRETTY_GENERATE_OPTS.merge(opts) if pretty
+    end
+    reformat_file_native(path, opts)
+  end
+
+  # Byte-splicing edits: replaces the values at the given JSON Pointers
+  # directly in the text. Every target resolves in ONE forward pass
+  # (skipping, not parsing), and the result is built in one sweep:
+  # every byte outside the target spans is copied untouched, so
+  # formatting, key order, and number spellings elsewhere are preserved
+  # exactly. For tweaking a field in a passing payload this replaces
+  # the whole parse → mutate → generate cycle.
+  #
+  # @example
+  #   NOSJ.splice(json, "/config/timeout" => 30)
+  #   NOSJ.splice(json, "/a" => 1, "/b/c" => [true])   # batch, one pass
+  #
+  # @param json [String] the document (UTF-8 or US-ASCII)
+  # @param edits [Hash{String => Object}] JSON Pointer => replacement
+  #   value (generated compactly, byte-identical to {.generate})
+  # @param opts [Hash, nil] {.generate} options for the inserted values
+  # @return [String] the edited document
+  # @raise [KeyError] when a pointer does not resolve (splice replaces;
+  #   use {.patch} +add+ to insert)
+  # @raise [ArgumentError] for malformed pointers or overlapping targets
+  # @raise [ParserError] when the document is malformed
+  def self.splice(json, edits, opts = nil)
+    splice_native(json, edits, opts)
+  end
+
+  # Applies an RFC 6902 JSON Patch to the raw document: +add+,
+  # +remove+, +replace+, +move+, +copy+, and +test+, applied
+  # sequentially, each as a byte-splice (structural ops walk only the
+  # parent container's span). Op hashes accept String or Symbol keys.
+  #
+  # @example
+  #   NOSJ.patch(json, [
+  #     {"op" => "test", "path" => "/a", "value" => 1},
+  #     {"op" => "replace", "path" => "/a", "value" => 2},
+  #     {"op" => "add", "path" => "/list/-", "value" => "x"},
+  #     {"op" => "move", "from" => "/tmp", "path" => "/kept"}
+  #   ])
+  #
+  # @param json [String] the document (UTF-8 or US-ASCII)
+  # @param ops [Array<Hash>] RFC 6902 operations
+  # @param opts [Hash, nil] {.generate} options for inserted values
+  # @return [String] the patched document
+  # @raise [PatchError] when application fails (failed +test+, missing
+  #   target, index out of range, move into own child)
+  # @raise [ArgumentError] for structurally malformed patch documents
+  # @raise [ParserError] when the document is malformed
+  def self.patch(json, ops, opts = nil)
+    patch_native(json, ops, opts)
+  end
+
+  # Applies an RFC 7386 JSON Merge Patch: +nil+ values remove keys,
+  # nested Hashes merge recursively, everything else replaces. This is
+  # the semantic form (parse, merge, generate); Symbol keys in +patch+
+  # match String keys in the document.
+  #
+  # @example
+  #   NOSJ.merge_patch(%({"a":{"b":1,"c":2}}), {a: {b: nil, d: 3}})
+  #   #=> '{"a":{"c":2,"d":3}}'
+  #
+  # @param json [String] the document (UTF-8 or US-ASCII)
+  # @param patch [Object] the merge patch (a non-Hash replaces the
+  #   whole document)
+  # @param opts [Hash, nil] {.generate} options for the result
+  # @return [String] the merged document
+  # @raise [ParserError] when the document is malformed
+  def self.merge_patch(json, patch, opts = nil)
+    return generate(patch, opts) unless patch.is_a?(Hash)
+    generate(merge_patch_value(parse(json), patch), opts)
+  end
+
+  # RFC 7386, applied to parsed values.
+  def self.merge_patch_value(target, patch)
+    return patch unless patch.is_a?(Hash)
+    target = {} unless target.is_a?(Hash)
+    out = target.dup
+    patch.each do |key, value|
+      key = key.to_s
+      if value.nil?
+        out.delete(key)
+      else
+        out[key] = merge_patch_value(out[key], value)
+      end
+    end
+    out
+  end
+  private_class_method :merge_patch_value
+
+  # NDJSON / JSON Lines: yields one parsed value per line of +source+.
+  # Framing is exact because a raw newline can never occur inside a
+  # JSON value; blank lines are skipped (the NDJSON convention). One
+  # value per line is enforced: a second value on a line raises, and a
+  # malformed line raises {ParserError} whose {ParserError#line} is the
+  # physical line number in +source+.
+  #
+  # Pass a frozen string for zero-copy iteration (an unfrozen source is
+  # walked over a private copy, like {.lazy}). The block may itself
+  # call any NOSJ method.
+  #
+  # @example
+  #   NOSJ.each_line(log) { |event| ingest(event) }
+  #   NOSJ.each_line(log).first(10)          # Enumerator when blockless
+  #
+  # @param source [String] newline-delimited JSON (UTF-8 or US-ASCII)
+  # @param opts [Hash, nil] the same options as {.parse}, applied per line
+  # @yieldparam value [Object] one parsed document per non-blank line
+  # @return [Enumerator] when no block is given, else +nil+
+  # @raise [ParserError] on the first malformed line
+  def self.each_line(source, opts = nil, &block)
+    return enum_for(:each_line, source, opts) unless block
+    each_line_native(source, opts, &block)
+  end
+
+  # {.each_line} against a file: the NDJSON stream is walked over a
+  # read-only memory map, so the file never becomes a Ruby String.
+  #
+  # @example
+  #   NOSJ.each_line_file("events.ndjson") { |event| ingest(event) }
+  #
+  # @param path [String] the NDJSON file (UTF-8)
+  # @param opts [Hash, nil] the same options as {.parse}, applied per line
+  # @yieldparam value [Object] one parsed document per non-blank line
+  # @return [Enumerator] when no block is given, else +nil+
+  # @raise [SystemCallError] +Errno::ENOENT+ and friends
+  # @raise [ParserError] on the first malformed line
+  def self.each_line_file(path, opts = nil, &block)
+    return enum_for(:each_line_file, path, opts) unless block
+    each_line_file_native(path, opts, &block)
+  end
+
+  # Generates NDJSON / JSON Lines: one compact document per element,
+  # each terminated with a newline, built in a single pass into one
+  # buffer. Formatting options containing newlines raise ArgumentError
+  # (they would break the line framing); everything else from
+  # {.generate} applies.
+  #
+  # @example
+  #   NOSJ.generate_lines([{a: 1}, {b: 2}])  #=> %({"a":1}\n{"b":2}\n)
+  #
+  # @param values [Array, Enumerable] one document per element
+  # @param opts [Hash, nil] the same options as {.generate}
+  # @return [String] the NDJSON document (empty when +values+ is empty)
+  # @raise [ArgumentError] for formatting options that contain newlines
+  # @raise [GeneratorError] (see {.generate})
+  def self.generate_lines(values, opts = nil)
+    generate_lines_native(lines_array(values), opts)
+  end
+
+  # {.generate_lines} straight to a file, streaming the generator's
+  # buffer to disk like {.write_file}.
+  #
+  # @example
+  #   NOSJ.write_lines("out.ndjson", events)  #=> bytes written
+  #
+  # @param path [String] the file to (over)write
+  # @param values [Array, Enumerable] one document per line
+  # @param opts [Hash, nil] the same options as {.generate}
+  # @return [Integer] the number of bytes written, like File.write
+  # @raise [SystemCallError] +Errno::ENOENT+ and friends
+  # @raise [ArgumentError] for formatting options that contain newlines
+  # @raise [GeneratorError] (see {.generate})
+  def self.write_lines(path, values, opts = nil)
+    write_lines_native(path, lines_array(values), opts)
+  end
+
+  # One document per element: Arrays pass through, other Enumerables
+  # convert, anything else (nil included, whose to_a would silently
+  # yield []) is a TypeError.
+  def self.lines_array(values)
+    return values if values.is_a?(Array)
+    unless values.is_a?(Enumerable)
+      raise TypeError, "no implicit conversion of #{values.class} into Array"
+    end
+    values.to_a
+  end
+  private_class_method :lines_array
+
+  # Document statistics from one full-parser pass into a counting sink:
+  # no Ruby value is built for the document itself, only the small
+  # result Hash. A debugging endpoint for "what is this 40 MB blob".
+  #
+  # The result (Symbol keys):
+  #
+  #   {
+  #     byte_size: 631,             # of the document
+  #     root: :object,              # :object/:array/:string/:integer/
+  #                                 # :float/:boolean/:null
+  #     max_depth: 4,               # container nesting, counted like
+  #                                 # max_nesting (root container = 1)
+  #     values: {total:, objects:, arrays:, strings:, integers:,
+  #              floats:, booleans:, nulls:},
+  #     keys: {total:, unique:},
+  #     key_histogram: {"name" => 128, ...},  # sorted by count desc,
+  #                                           # so .first(10) = top 10
+  #     containers: {max_object_entries:, max_array_length:},
+  #     strings: {bytes:, max_bytes:}         # decoded UTF-8 bytes
+  #   }
+  #
+  # Unlike {.parse}, nesting is UNLIMITED by default (a deep blob is
+  # exactly what a diagnostic should describe); pass +max_nesting+ to
+  # enforce a limit. Histogram memory is proportional to the number of
+  # unique keys.
+  #
+  # @example Top ten keys of a mystery blob
+  #   NOSJ.stats(blob)[:key_histogram].first(10)
+  #
+  # @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)
+  # @return [Hash] the statistics described above
+  # @raise [ParserError] when the document is malformed or not UTF-8
+  def self.stats(source, opts = nil)
+    stats_native(source, opts)
+  end
+
+  # {.stats} against a file: memory-maps it and runs the counting pass
+  # without reading the document into Ruby. +byte_size+ is the file
+  # size.
+  #
+  # @example
+  #   NOSJ.stats_file("huge.json") => {byte_size: 41_943_040, ...}
+  #
+  # @param path [String] the file to inspect (UTF-8)
+  # @param opts [Hash, nil] same options as {.stats}
+  # @return [Hash] the statistics described on {.stats}
+  # @raise [SystemCallError] +Errno::ENOENT+ and friends
+  # @raise [ParserError] when the file is malformed or not UTF-8
+  def self.stats_file(path, opts = nil)
+    stats_file_native(path, opts)
+  end
 end

data/sig/nosj.rbs

@@ -25,12 +25,32 @@ module NOSJ
   class Error < StandardError
   end
 
+  # Parse failures. Position accessors are nil for failures without
+  # one (encoding refusals); positions are byte-absolute within the
+  # document, lines and (character) columns 1-based.
+  class ParserError < Error
+    def byte_offset: () -> Integer?
+
+    def line: () -> Integer?
+
+    def column: () -> Integer?
+
+    def snippet: () -> String?
+
+    def detailed_message: (?highlight: bool, **untyped) -> String
+  end
+
   class GeneratorError < Error
   end
 
   class NestingError < Error
   end
 
+  # RFC 6902 application failures (failed test, missing target, index
+  # out of range, move into own child).
+  class PatchError < Error
+  end
+
   def self.parse: (String source, ?opts opts) -> value
 
   def self.generate: (untyped obj, ?opts opts) -> String
@@ -39,6 +59,12 @@ module NOSJ
 
   def self.valid?: (String source, ?opts opts) -> bool
 
+  # Document statistics (byte_size, root, max_depth, values, keys,
+  # key_histogram, containers, strings) from one counting-sink pass.
+  def self.stats: (String source, ?opts opts) -> Hash[Symbol, untyped]
+
+  def self.stats_file: (String path, ?opts opts) -> Hash[Symbol, untyped]
+
   def self.dig: (String source, *path_element path) -> value
 
   def self.dig_many: (String source, Array[Array[path_element]] paths, ?opts opts) -> Array[value]
@@ -49,6 +75,36 @@ module NOSJ
 
   def self.lazy: (String source, ?opts opts) -> (Lazy | value)
 
+  # Reformat without building values: parser events pipe straight into
+  # the emission kernels. minify is compact; reformat takes pretty: and
+  # the generate formatting/escape options.
+  def self.minify: (String json, ?opts opts) -> String
+
+  def self.reformat: (String json, ?opts opts) -> String
+
+  def self.reformat_file: (String path, ?opts opts) -> String
+
+  # Byte-splicing edits: JSON Pointer => replacement value, resolved
+  # in one pass; bytes outside the target spans are copied untouched.
+  def self.splice: (String json, Hash[String, untyped] edits, ?opts opts) -> String
+
+  # RFC 6902 JSON Patch over the raw document.
+  def self.patch: (String json, Array[Hash[untyped, untyped]] ops, ?opts opts) -> String
+
+  # RFC 7386 JSON Merge Patch (semantic: parse, merge, generate).
+  def self.merge_patch: (String json, untyped patch, ?opts opts) -> String
+
+  # NDJSON / JSON Lines: one parsed value per non-blank line.
+  def self.each_line: (String source, ?opts opts) { (value) -> void } -> nil
+                    | (String source, ?opts opts) -> Enumerator[value, nil]
+
+  def self.each_line_file: (String path, ?opts opts) { (value) -> void } -> nil
+                         | (String path, ?opts opts) -> Enumerator[value, nil]
+
+  def self.generate_lines: (_Each[untyped] values, ?opts opts) -> String
+
+  def self.write_lines: (String path, _Each[untyped] values, ?opts opts) -> Integer
+
   def self.load_file: (String path, ?opts opts) -> value
 
   def self.write_file: (String path, untyped obj, ?opts opts) -> Integer
@@ -101,6 +157,16 @@ module NOSJ
     alias to_s inspect
   end
 
+  # Defined by `require "nosj/rails"`, which also installs it as
+  # ActiveSupport::JSON::Encoding.json_encoder.
+  class RailsEncoder
+    attr_reader options: Hash[Symbol, untyped]
+
+    def initialize: (?Hash[Symbol, untyped]? options) -> void
+
+    def encode: (untyped value) -> String
+  end
+
   # Defined by `require "nosj/multi_json"`. The runtime superclass is
   # multi_json's Adapter (whose namespace differs across multi_json
   # versions), so it is not declared here.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nosj
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
 platform: x86_64-linux
 authors:
 - Yaroslav Markin
@@ -14,7 +14,9 @@ description: 'gem nosj is an extremely fast, json-gem-compatible JSON parser and
   with per-platform PGO, partial parsing (JSON Pointer, single and batch), lazy documents
   that parse a value only when you touch it, file APIs that parse, generate, and query
   files natively (memory-mapped, so unread pages never leave the disk), allocation-free
-  validation, and a one-line JSON module drop-in.'
+  validation, document statistics from one counting pass, parse errors that carry
+  line, column, and a caret snippet, a one-line JSON module drop-in, and a Rails mode
+  that plugs into ActiveSupport''s encoder seam.'
 email:
 - yaroslav@markin.net
 executables: []
@@ -33,6 +35,7 @@ files:
 - lib/nosj/lazy.rb
 - lib/nosj/multi_json.rb
 - lib/nosj/native.rb
+- lib/nosj/rails.rb
 - lib/nosj/version.rb
 - sig/nosj.rbs
 homepage: https://github.com/yaroslav/nosj-ruby