nosj 0.1.0-x86_64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0a0fd640bbecb91b12ed17a8ee5edc5b87befe85b1fcdcd124c58624255b3d02
+  data.tar.gz: 6cc111ee1c0a1d55640325d48e5b71fad155f18d218211a9fcaf2f3f2a3a54b7
+SHA512:
+  metadata.gz: 6dcc90744851a53f59a088e2ea4429ece7df99e2b72cbe81d049818641beb500b6847b9a3d9f703094c6d2f9aec669c89ab3ae652d47d29a8f3cefe0ee195ba9
+  data.tar.gz: 1f50198d497a46a8abbd281934ce3a04e5a704a1cbec221e2cf1dc0d570de817e447c4eb580c61e288960d5c797ba8f3f7b5e9215e85f90b439ae02e9dce57db

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+## [0.1.0] - 2026-07-15
+
+Initial release.
+
+- `NOSJ.parse`, `NOSJ.generate`, and `NOSJ.pretty_generate`: `json`-gem-compatible parsing and generation—same output bytes, same option names, same error classes and messages—built on the first-party SIMD [nosj](https://crates.io/crates/nosj) crate (NEON on Apple Silicon; SSE2/AVX2 on x86-64, selected at runtime). Faster than the `json` gem and the third-party parsers (Oj, RapidJSON, FastJsonparser, Yajl) across the benchmark corpus, in both directions.
+- Partial parsing: `NOSJ.dig` and `NOSJ.at_pointer` resolve a JSON Pointer and materialize only the matched subtree; `NOSJ.dig_many` and `NOSJ.at_pointers` resolve whole batches of paths in a single pass over the document.
+- `NOSJ.valid?`: full-strictness validation that allocates no Ruby objects.
+- Drop-in acceleration: `require "nosj/json"` reroutes `JSON.parse`, `JSON.generate`, `JSON.pretty_generate`, and `JSON.dump` through nosj, falling back to the original implementation for unsupported options; `require "nosj/multi_json"` adds a MultiJson adapter.
+- Precompiled platform gems, each built natively with profile-guided optimization: Linux x86-64 and arm64 (glibc and musl), macOS (Apple Silicon), Windows (x64), for Ruby 3.3 through 4.0. Other platforms compile the source gem.
+- RBS signatures and full YARD documentation.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yaroslav Markin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/NOTICE

@@ -0,0 +1,13 @@
+nosj (Ruby gem)
+
+Copyright (c) 2026 Yaroslav Markin. Released under the MIT License
+(see LICENSE.txt).
+
+Every distribution of this gem embeds the nosj Rust crate
+(https://github.com/yaroslav/nosj), compiled into the native
+extension: precompiled platform gems ship the compiled binary, and the
+source gem compiles the crate at install time. The crate is licensed
+MIT AND BSL-1.0 AND Apache-2.0; its NOTICE file itemizes the derived
+components (the fpconv/Grisu2 float formatter under BSL-1.0; the
+fast_float decimal conversion and simdjson structural-indexing
+techniques under Apache-2.0) and reproduces each component license.

data/README.md

@@ -0,0 +1,214 @@
+# gem nosj
+
+**gem nosj** is an **very fast JSON parser and generator for Ruby**, written in Rust on the first-party [nosj](https://github.com/yaroslav/nosj) crate and **SIMD-accelerated** on every platform (NEON on Apple Silicon, SSE2/AVX2 on x86-64).
+
+> gem nosj is the powerful evil twin of the json gem.
+
+[![GitHub Release](https://img.shields.io/github/v/release/yaroslav/nosj-ruby)](https://github.com/yaroslav/nosj-ruby/releases)
+[![Docs](https://img.shields.io/badge/yard-docs-blue.svg)](https://rubydoc.info/gems/nosj)
+
+- It is **faster** than gem json and every
+third-party parser, including Oj, RapidJSON, FastJsonparser, Yajl. 1.0–1.8× faster than the bundled json gem, 1.3–11× faster than Oj, and up to 17×
+faster than Yajl—[see Benchmarks](#benchmarks).
+- It comes **precompiled** (platform gems built with per-platform optimizations,
+nothing to compile on install).
+- It has a **partial parsing mode**: JSON Pointer lookups that pull single values out of big documents in microseconds, skipping everything else.
+- 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.
+
+- [Requirements](#requirements)
+- [Getting started](#getting-started)
+- [What's in the box](#whats-in-the-box)
+- [Benchmarks](#benchmarks)
+- [Switching from the json gem](#switching-from-the-json-gem)
+- [How it works](#how-it-works)
+- [Development](#development)
+- [License](#license)
+
+## Requirements
+
+- **Ruby 3.3 or newer** (CRuby; tested on 3.3, 3.4, and 4.0).
+- **Linux** (x86-64 and arm64, glibc and musl), **macOS** (Apple
+  Silicon), or **Windows** (x64): these platforms install precompiled,
+  per-platform-optimized gems with nothing to build.
+
+## Getting started
+
+```bash
+bundle add nosj
+```
+
+```ruby
+require "nosj"
+
+NOSJ.parse('{"a":[1,true]}')       #=> {"a" => [1, true]}
+NOSJ.generate({"a" => [1, true]})  #=> '{"a":[1,true]}'
+```
+
+That's it—if you know the `json` gem, you already know `nosj`.
+
+Want the speedup without touching your code? One line reroutes
+`JSON.parse`, `JSON.generate`, `JSON.pretty_generate`, and `JSON.dump`
+through nosj:
+
+```ruby
+require "nosj/json"
+```
+
+In a Bundler app (Rails included) that can live entirely in the
+Gemfile you can do this:
+
+```ruby
+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`.)
+
+## What's in the box
+
+**The `json` gem API**, on the `NOSJ` module:
+
+```ruby
+NOSJ.parse(src, symbolize_names: true)   # also: freeze, max_nesting,
+                                         # allow_nan, allow_trailing_comma
+NOSJ.generate(obj)                       # indent, space, object_nl, ...,
+NOSJ.pretty_generate(obj)                # ascii_only, script_safe, strict
+```
+
+**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:
+
+```ruby
+NOSJ.valid?('{"a":1}')                #=> true
+NOSJ.valid?('{"a":}')                 #=> false
+NOSJ.valid?(src, max_nesting: false)  # same options as parse
+```
+
+**Partial parsing.** 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:
+
+```ruby
+NOSJ.dig(json, "users", 3, "name")        # Hash#dig-shaped
+NOSJ.at_pointer(json, "/users/3/name")    # JSON Pointer
+
+# Many lookups in one pass. A batch costs about as much as its
+# single deepest member:
+NOSJ.at_pointers(json, ["/users/3/name", "/meta/count"])
+NOSJ.dig_many(json, [["users", 3, "name"], ["meta", "count"]])
+```
+
+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:`).
+
+## 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. 
+
+Parse:
+
+| file | nosj (i/s) | json | Oj | FastJsonparser | RapidJSON | Yajl |
+|---|---:|---:|---:|---:|---:|---:|
+| activitypub | **12.4k** | ×1.18 | ×1.53 | ×1.89 | ×1.99 | ×4.57 |
+| canada | **248** | ×1.10 | ×8.28 | ×1.45 | ×1.51 | ×4.96 |
+| citm_catalog | **504** | ×1.03 | ×1.97 | ×2.07 | ×1.83 | ×4.93 |
+| gsoc-2018 | **397** | ×1.30 | ×1.47 | ×1.81 | ×1.80 | ×4.78 |
+| homebrew-formula | **15.2** | ×1.13 | ×1.54 | ×2.42 | ×2.02 | ×4.30 |
+| homebrew-llvm | **49.3k** | ×1.60 | ×1.48 | ×1.50 | ×1.85 | ×5.11 |
+| mesh | **1.1k** | ×1.30 | ×3.93 | ×1.82 | ×1.95 | ×6.96 |
+| numbers | **5.9k** | ×1.19 | ×4.64 | ×1.43 | ×1.75 | ×7.04 |
+| ohai | **14.4k** | ×1.47 | ×1.61 | ×2.11 | ×1.97 | ×4.71 |
+| simple | **977k** | ×1.31 | ×1.77 | ×2.08 | ×1.63 | ×5.15 |
+| small_mixed | **3.2M** | ×1.48 | ×2.85 | ×2.44 | ×1.82 | ×6.75 |
+| tolstoy | **8.9k** | ×1.79 | ×1.96 | ×2.29 | ×2.10 | ×17.31 |
+| twitter | **1.1k** | ×1.09 | ×1.83 | ×2.25 | ×2.61 | ×5.40 |
+
+Generate:
+
+| file | nosj (i/s) | json | Oj | RapidJSON | Yajl |
+|---|---:|---:|---:|---:|---:|
+| activitypub | **34.8k** | ×1.20 | ×1.78 | ×2.41 | ×5.84 |
+| canada | **150** | ×0.98\* | ×10.98 | ×11.20 | ×10.87 |
+| citm_catalog | **1.3k** | ×1.04 | ×1.44 | ×1.55 | ×2.85 |
+| gsoc-2018 | **1.1k** | ×1.28 | ×2.64 | ×3.64 | ×11.00 |
+| homebrew-formula | **20.9** | ×1.07 | ×1.25 | ×1.62 | ×3.03 |
+| homebrew-llvm | **71.5k** | ×1.23 | ×2.22 | ×3.04 | ×5.80 |
+| mesh | **613** | ×1.08 | ×9.24 | ×9.40 | ×9.26 |
+| numbers | **2.1k** | ×1.03 | ×10.63 | ×11.00 | ×10.69 |
+| ohai | **39.4k** | ×1.07 | ×1.29 | ×1.50 | ×3.37 |
+| simple | **2.2M** | ×1.03 | ×1.58 | ×1.62 | ×4.36 |
+| small_mixed | **5.6M** | ×1.09 | ×2.26 | ×1.83 | ×7.16 |
+| tolstoy | **8.3k** | ×1.30 | ×4.15 | ×6.50 | ×14.54 |
+| twitter | **2.9k** | ×1.09 | ×1.46 | ×2.01 | ×4.05 |
+
+\* canada-generate is a statistical tie with the json gem (within
+measurement error).
+
+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
+
+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.
+- 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).
+
+Everything else—including the gem's exact float formatting, which is
+not the shortest-round-trip form most libraries emit—matches
+byte-for-byte and is verified continuously against the full corpus.
+
+## How it works
+
+Most fast parsers build their own tree first and convert it into Ruby
+objects second, paying for every string and container twice. nosj is
+built on the [nosj](https://github.com/yaroslav/nosj) Rust crate, an
+event parser with no tree of its own:
+
+- **No intermediate tree.** The crate parses with NEON/SSE2/AVX2 SIMD
+  kernels and emits *events*; the extension builds interned hash keys,
+  strings, and containers directly on Ruby's heap during the parse,
+  with GC-safe value stacks and epoch-evicted key caches. Generation
+  walks Ruby objects once, streaming through fused scan-and-store
+  escape kernels.
+- **Byte-exact floats.** Output reproduces the json gem's fpconv
+  (Grisu2) float format digit for digit—round-tripping is verified,
+  not assumed.
+- **PGO everywhere.** Local builds, CI, and every precompiled platform
+  gem train on the benchmark corpus before the shipping compile; the
+  precompiled binaries use portable codegen with SIMD tiers detected at
+  runtime.
+
+## Development
+
+```bash
+bundle exec rake compile                # build the extension (applies a PGO profile if present)
+bundle exec rake spec                   # the gem-parity suite
+bundle exec rake bench                  # PGO retrain + the parity-gated sweep vs the json gem
+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
+```
+
+## License
+
+MIT. The underlying Rust crate is `MIT AND BSL-1.0 AND Apache-2.0`; its
+NOTICE file itemizes the derived components.

data/lib/nosj/json.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+# Drop-in acceleration for the JSON module:
+#
+#   require "nosj/json"
+#
+# 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
+# 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!,
+# 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).
+#
+# 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).
+#
+# Not rerouted: obj.to_json (core extensions drive the gem's generator
+# directly), and objects with a custom to_json inside a rerouted
+# generate receive no State argument (documented NOSJ divergence).
+
+require "json"
+require "nosj"
+
+module NOSJ
+  # Implementation detail of `require "nosj/json"`.
+  # @private
+  module JSONDropIn
+    PARSE_OPTS = %i[symbolize_names freeze max_nesting allow_nan
+      allow_trailing_comma].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
+
+    module_function
+
+    # 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.
+    def supported?(opts, allowed)
+      return true if opts.nil?
+      return false unless opts.instance_of?(Hash)
+      opts.each_key { |k| return false unless allowed.include?(k) }
+      true
+    end
+
+    def parse(source, opts)
+      NOSJ.parse(source, opts)
+    rescue RuntimeError => e
+      raise ::JSON::ParserError, e.message
+    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
+    end
+  end
+end
+
+# Reopened by `require "nosj/json"` to reroute the module functions
+# through NOSJ; behavior is documented on the require and in the
+# README, not here.
+# @private
+module JSON
+  class << self
+    unless method_defined?(:nosj_original_parse) || private_method_defined?(:nosj_original_parse)
+      alias_method :nosj_original_parse, :parse
+      alias_method :nosj_original_generate, :generate
+      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)
+        end
+      end
+
+      def generate(obj, opts = nil)
+        if NOSJ::JSONDropIn.supported?(opts, NOSJ::JSONDropIn::GENERATE_OPTS)
+          NOSJ::JSONDropIn.generate(obj, opts, false)
+        else
+          nosj_original_generate(obj, opts)
+        end
+      end
+
+      def pretty_generate(obj, opts = nil)
+        if NOSJ::JSONDropIn.supported?(opts, NOSJ::JSONDropIn::GENERATE_OPTS)
+          NOSJ::JSONDropIn.generate(obj, opts, true)
+        else
+          nosj_original_pretty_generate(obj, opts)
+        end
+      end
+
+      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
+        # user's options, NestingError surfaced as ArgumentError. IO and
+        # limit arguments take the original implementation.
+        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
+          if NOSJ::JSONDropIn.supported?(opts, NOSJ::JSONDropIn::GENERATE_OPTS)
+            begin
+              return NOSJ::JSONDropIn.generate(obj, opts, false)
+            rescue ::JSON::NestingError
+              raise ArgumentError, "exceed depth limit"
+            end
+          end
+        end
+        nosj_original_dump(obj, an_io, limit, kwargs)
+      end
+    end
+  end
+end

data/lib/nosj/multi_json.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# MultiJson adapter:
+#
+#   require "nosj/multi_json"
+#   MultiJson.use NOSJ::MultiJsonAdapter
+#
+# Anything speaking MultiJson (Faraday middleware and friends) then
+# parses and generates through NOSJ.
+
+require "json"
+require "multi_json"
+require "multi_json/adapter"
+require "nosj"
+
+module NOSJ
+  # MultiJson adapter routing +MultiJson.load+/+dump+ through nosj.
+  #
+  # multi_json 2.x renamed its namespace MultiJson -> MultiJSON; the
+  # adapter inherits from whichever this installation defines.
+  #
+  # @example
+  #   require "nosj/multi_json"
+  #   MultiJson.use NOSJ::MultiJsonAdapter
+  class MultiJsonAdapter < (defined?(::MultiJSON) ? ::MultiJSON::Adapter : ::MultiJson::Adapter)
+    # MultiJson wraps whatever the adapter's ParseError names.
+    ParseError = ::JSON::ParserError
+
+    SYMBOLIZE = {symbolize_names: true}.freeze
+    private_constant :SYMBOLIZE
+
+    # @param string [String] the JSON document
+    # @param options [Hash] multi_json load options; +symbolize_keys+
+    #   arrives normalized as +symbolize_names+
+    # @return [Object] the parsed value tree
+    # @raise [JSON::ParserError] when the document is malformed
+    def load(string, options = {})
+      ::NOSJ.parse(string, options[:symbolize_names] ? SYMBOLIZE : nil)
+    rescue RuntimeError => e
+      raise ParseError, e.message
+    end
+
+    # @param object [Object] the value tree to serialize
+    # @param options [Hash] multi_json dump options; +pretty+ selects
+    #   pretty-printing
+    # @return [String] the JSON document
+    def dump(object, options = {})
+      options[:pretty] ? ::NOSJ.pretty_generate(object) : ::NOSJ.generate(object)
+    end
+  end
+end

data/lib/nosj/native.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Precompiled platform gems ship one extension per Ruby minor under
+# lib/nosj/<major.minor>/; the source gem compiles straight to
+# lib/nosj/nosj.<dlext>.
+begin
+  ruby_version = RUBY_VERSION[/\d+\.\d+/]
+  require_relative "#{ruby_version}/nosj"
+rescue LoadError
+  require_relative "nosj"
+end

data/lib/nosj/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module NOSJ
+  # The gem version.
+  VERSION = "0.1.0"
+end

data/lib/nosj.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require_relative "nosj/version"
+require_relative "nosj/native"
+
+# nosj is the evil twin of the +json+ gem: the same API, output bytes,
+# option names, and error messages, backed by the Rust
+# {https://github.com/yaroslav/nosj nosj} crate with SIMD-accelerated
+# parsing and generation. Beyond the +json+ gem's surface it adds
+# zero-allocation validation ({.valid?}) and partial parsing
+# ({.dig}, {.at_pointer}, and their batch forms).
+#
+# Options arrive as a positional Hash (the +json+ gem's own calling
+# convention); an explicit +**kwargs+ would allocate per call.
+#
+# @example The json gem API
+#   NOSJ.parse('{"a":[1,true]}')        #=> {"a" => [1, true]}
+#   NOSJ.generate({"a" => [1, true]})   #=> '{"a":[1,true]}'
+#
+# @example Drop-in acceleration for the JSON module
+#   require "nosj/json"
+#   JSON.parse(src)  # routed through nosj
+module NOSJ
+  # Base class for nosj errors.
+  class Error < StandardError; 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+.
+  class NestingError < Error; end
+
+  PRETTY_GENERATE_OPTS = {
+    indent: "  ", space: " ", object_nl: "\n", array_nl: "\n"
+  }.freeze
+  private_constant :PRETTY_GENERATE_OPTS
+
+  # 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.
+  #
+  # @example
+  #   NOSJ.parse('{"a":[1,true]}')                      #=> {"a" => [1, true]}
+  #   NOSJ.parse('{"a":1}', symbolize_names: true)      #=> {a: 1}
+  #
+  # @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+
+  # @return [Object] the parsed value tree
+  # @raise [RuntimeError] when the document is malformed or not UTF-8
+  # @raise [ArgumentError] for unsupported options
+  def self.parse(source, opts = nil)
+    parse_native(source, opts)
+  end
+
+  # @!method self.generate(obj, opts = nil)
+  #   Generates JSON, JSON.generate-compatible: identical output bytes,
+  #   including the gem's exact float formatting. Implemented natively
+  #   (no Ruby forwarder frame; the definition lives in the extension).
+  #
+  #   @example
+  #     NOSJ.generate({"a" => [1, true]})  #=> '{"a":[1,true]}'
+  #
+  #   @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+
+  #   @return [String] the JSON document
+  #   @raise [GeneratorError] for non-finite floats without +allow_nan+,
+  #     unsupported objects under +strict+, or broken string encodings
+  #   @raise [NestingError] when nesting exceeds +max_nesting+
+
+  # Generates human-readable JSON, JSON.pretty_generate-compatible
+  # (two-space indent, newlines between elements). Options override the
+  # pretty defaults and are otherwise the same as {.generate}.
+  #
+  # @param obj [Object] the value tree to serialize
+  # @param opts [Hash, nil] see {.generate}
+  # @return [String] the pretty-printed JSON document
+  # @raise [GeneratorError] (see {.generate})
+  # @raise [NestingError] (see {.generate})
+  def self.pretty_generate(obj, opts = nil)
+    opts = opts.nil? ? PRETTY_GENERATE_OPTS : PRETTY_GENERATE_OPTS.merge(opts)
+    generate_native(obj, opts)
+  end
+
+  # Validates a document without building any Ruby values: the full
+  # parser (tokenizers, string decode, number validation) runs into a
+  # null sink, 1.8-2.5x faster than {.parse}.
+  #
+  # Returns true iff <code>NOSJ.parse(source, opts)</code> would
+  # succeed: parse refusals (malformed JSON, wrong encoding, too-deep
+  # nesting) are +false+, while option and argument-type errors still
+  # raise exactly like {.parse}.
+  #
+  # @example
+  #   NOSJ.valid?('{"a":1}')  #=> true
+  #   NOSJ.valid?('{"a":}')   #=> false
+  #
+  # @param source [String] the JSON document
+  # @param opts [Hash, nil] same options as {.parse}
+  # @return [Boolean]
+  # @raise [ArgumentError] for unsupported options
+  def self.valid?(source, opts = nil)
+    valid_native(source, opts)
+  end
+
+  # Partial parsing, Hash#dig-shaped: extracts one value from a JSON
+  # string without materializing the rest of the document. Skipped
+  # content is stepped over at SIMD block speed, so a lookup costs what
+  # it skips, not what the document weighs.
+  #
+  # @example
+  #   NOSJ.dig(json, "users", 3, "name")  #=> "grace" or nil
+  #
+  # @param source [String] the JSON document
+  # @param path [Array<String, Symbol, Integer>] object keys and array
+  #   indices; unlike Array#dig, negative indices return +nil+ (JSON
+  #   Pointer has no equivalent)
+  # @return [Object, nil] the matched value, or +nil+ when the path
+  #   does not resolve
+  # @raise [ArgumentError] for path elements that are not Strings,
+  #   Symbols, or Integers
+  def self.dig(source, *path)
+    dig_native(source, path)
+  end
+
+  # Batch {.dig}: many paths resolved in ONE pass over the document.
+  # The walk descends only into subtrees some path still needs, so a
+  # batch costs about as much as its single deepest lookup.
+  #
+  # On malformed documents a batch may raise where a single dig would
+  # return +nil+: one pass scans every byte some path needs.
+  #
+  # @example
+  #   NOSJ.dig_many(json, [["users", 3, "name"], ["meta", "count"]])
+  #   #=> ["grace", 42]
+  #
+  # @param source [String] the JSON document
+  # @param paths [Array<Array<String, Symbol, Integer>>] one dig path
+  #   per result
+  # @param opts [Hash, nil] materialization options ({.parse}'s
+  #   +symbolize_names+, +freeze+, ...)
+  # @return [Array<Object, nil>] positionally aligned with +paths+
+  # @raise [ArgumentError] for malformed paths
+  def self.dig_many(source, paths, opts = nil)
+    dig_many_native(source, paths, opts)
+  end
+
+  # Partial parsing by JSON Pointer (with the standard +~0+/+~1+
+  # escapes). The matched subtree materializes under the same options
+  # as {.parse}.
+  #
+  # @example
+  #   NOSJ.at_pointer(json, "/users/3/name")  #=> "grace" or nil
+  #
+  # @param source [String] the JSON document
+  # @param pointer [String] a JSON Pointer (empty string = whole
+  #   document)
+  # @param opts [Hash, nil] materialization options
+  # @return [Object, nil] the matched value, or +nil+ when the pointer
+  #   does not resolve
+  # @raise [ArgumentError] for a malformed pointer (non-empty without a
+  #   leading +/+)
+  def self.at_pointer(source, pointer, opts = nil)
+    at_pointer_native(source, pointer, opts)
+  end
+
+  # Batch {.at_pointer}: the pointer-string counterpart of {.dig_many},
+  # resolving the whole set in one pass.
+  #
+  # @example
+  #   NOSJ.at_pointers(json, ["/users/3/name", "/meta/count"])
+  #   #=> ["grace", 42]
+  #
+  # @param source [String] the JSON document
+  # @param pointers [Array<String>] JSON Pointers, one per result
+  # @param opts [Hash, nil] materialization options
+  # @return [Array<Object, nil>] positionally aligned with +pointers+
+  # @raise [ArgumentError] for malformed pointers
+  def self.at_pointers(source, pointers, opts = nil)
+    at_pointers_native(source, pointers, opts)
+  end
+end

data/sig/nosj.rbs

@@ -0,0 +1,61 @@
+# Public interfaces only. The native layer (NOSJ.parse_native and
+# friends) and the JSON drop-in's patched JSON singleton methods are
+# implementation detail and deliberately unsigned.
+module NOSJ
+  VERSION: String
+
+  # Any value JSON can represent, as Ruby objects: what parse returns
+  # and what partial parsing materializes. Object keys are String
+  # (Symbol with symbolize_names). generate accepts more than this
+  # alias (anything with to_json, unless strict), hence untyped there.
+  type value = nil | bool | Integer | Float | String
+             | Array[value] | Hash[String | Symbol, value]
+
+  # 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.
+  type opts = Hash[Symbol, untyped]?
+
+  # One NOSJ.dig path element (negative Integer indices resolve to nil).
+  type path_element = String | Symbol | Integer
+
+  class Error < StandardError
+  end
+
+  class GeneratorError < Error
+  end
+
+  class NestingError < Error
+  end
+
+  def self.parse: (String source, ?opts opts) -> value
+
+  def self.generate: (untyped obj, ?opts opts) -> String
+
+  def self.pretty_generate: (untyped obj, ?opts opts) -> String
+
+  def self.valid?: (String source, ?opts opts) -> bool
+
+  def self.dig: (String source, *path_element path) -> value
+
+  def self.dig_many: (String source, Array[Array[path_element]] paths, ?opts opts) -> Array[value]
+
+  def self.at_pointer: (String source, String pointer, ?opts opts) -> value
+
+  def self.at_pointers: (String source, Array[String] pointers, ?opts opts) -> Array[value]
+
+  # 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.
+  class MultiJsonAdapter
+    # multi_json wraps whatever the adapter's ParseError names.
+    ParseError: singleton(::JSON::ParserError)
+
+    def load: (String string, ?Hash[Symbol, untyped] options) -> value
+
+    def dump: (untyped object, ?Hash[Symbol, untyped] options) -> String
+  end
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: nosj
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: x86_64-linux
+authors:
+- Yaroslav Markin
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: 'gem nosj is an extremely fast, json-gem-compatible JSON parser and generator
+  for Ruby: Rust and SIMD via the first-party nosj crate, precompiled platform gems
+  with per-platform PGO, partial parsing (JSON Pointer, single and batch), allocation-free
+  validation, and a one-line JSON module drop-in.'
+email:
+- yaroslav@markin.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- NOTICE
+- README.md
+- lib/nosj.rb
+- lib/nosj/3.3/nosj.so
+- lib/nosj/3.4/nosj.so
+- lib/nosj/4.0/nosj.so
+- lib/nosj/json.rb
+- lib/nosj/multi_json.rb
+- lib/nosj/native.rb
+- lib/nosj/version.rb
+- sig/nosj.rbs
+homepage: https://github.com/yaroslav/nosj-ruby
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/yaroslav/nosj-ruby
+  source_code_uri: https://github.com/yaroslav/nosj-ruby
+  changelog_uri: https://github.com/yaroslav/nosj-ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/yaroslav/nosj-ruby/issues
+  documentation_uri: https://rubydoc.info/gems/nosj
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 4.1.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.11
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: An extremely fast JSON parser and generator for Ruby, written in Rust and
+  SIMD-accelerated on every platform.
+test_files: []