nosj 0.1.0 → 0.2.0

data/lib/nosj.rb

@@ -2,13 +2,15 @@
 
 require_relative "nosj/version"
 require_relative "nosj/native"
+require_relative "nosj/lazy"
 
 # 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).
+# zero-allocation validation ({.valid?}), partial parsing
+# ({.dig}, {.at_pointer}, and their batch forms), and lazy documents
+# ({.lazy}).
 #
 # Options arrive as a positional Hash (the +json+ gem's own calling
 # convention); an explicit +**kwargs+ would allocate per call.
@@ -190,4 +192,85 @@ module NOSJ
   def self.at_pointers(source, pointers, opts = nil)
     at_pointers_native(source, pointers, opts)
   end
+
+  # Parses a JSON file, like +JSON.load_file+—except the file is read
+  # natively into a reused buffer, so no file-sized Ruby String is ever
+  # created (or garbage-collected).
+  #
+  # @example
+  #   NOSJ.load_file("config.json", symbolize_names: true)
+  #
+  # @param path [String] the file to parse (UTF-8)
+  # @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
+  def self.load_file(path, opts = nil)
+    load_file_native(path, opts)
+  end
+
+  # Generates +obj+ as JSON and writes it to +path+, streaming the
+  # generator's buffer straight to disk—no intermediate Ruby String.
+  #
+  # @example
+  #   NOSJ.write_file("out.json", {"a" => [1, true]})   #=> 14
+  #   NOSJ.write_file("pretty.json", obj, indent: "  ", object_nl: "\n")
+  #
+  # @param path [String] the file to (over)write
+  # @param obj [Object] the value tree to generate
+  # @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, like File.write
+  # @raise [GeneratorError] like {.generate}
+  def self.write_file(path, obj, opts = nil)
+    write_file_native(path, obj, opts)
+  end
+
+  # Wraps a JSON file as a lazy document ({.lazy} for files): the file
+  # is memory-mapped read-only, so beyond one sequential UTF-8 check,
+  # pages you never read are never loaded from disk. The mapping lives
+  # as long as any node on it; the file must not be modified while it
+  # is in use.
+  #
+  # @example
+  #   doc = NOSJ.load_lazy_file("huge.json")
+  #   doc["users"][3]["name"]   # touches only these pages
+  #
+  # @param path [String] the file to wrap (UTF-8)
+  # @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
+  def self.load_lazy_file(path, opts = nil)
+    load_lazy_file_native(path, opts)
+  end
+
+  # {.at_pointer} against a file: memory-maps it, resolves the pointer,
+  # materializes only the matched subtree, and never reads the rest
+  # into Ruby.
+  #
+  # @example
+  #   NOSJ.at_pointer_file("huge.json", "/users/3/name")
+  #
+  # @param path [String] the file to query (UTF-8)
+  # @param pointer [String] an RFC 6901 JSON Pointer
+  # @param opts [Hash, nil] materialization options
+  # @return [Object, nil] nil when the pointer misses
+  # @raise [ArgumentError] for malformed pointers
+  def self.at_pointer_file(path, pointer, opts = nil)
+    at_pointer_file_native(path, pointer, opts)
+  end
+
+  # {.dig} against a file: the Hash#dig-shaped counterpart of
+  # {.at_pointer_file}. Negative indices resolve to nil.
+  #
+  # @example
+  #   NOSJ.dig_file("huge.json", "users", 3, "name")
+  #
+  # @param path [String] the file to query (UTF-8)
+  # @param path_elements [Array<String, Symbol, Integer>]
+  # @return [Object, nil]
+  def self.dig_file(path, *path_elements)
+    dig_file_native(path, path_elements)
+  end
 end

data/sig/nosj.rbs

@@ -47,6 +47,60 @@ module NOSJ
 
   def self.at_pointers: (String source, Array[String] pointers, ?opts opts) -> Array[value]
 
+  def self.lazy: (String source, ?opts opts) -> (Lazy | value)
+
+  def self.load_file: (String path, ?opts opts) -> value
+
+  def self.write_file: (String path, untyped obj, ?opts opts) -> Integer
+
+  def self.load_lazy_file: (String path, ?opts opts) -> (Lazy | value)
+
+  def self.at_pointer_file: (String path, String pointer, ?opts opts) -> value
+
+  def self.dig_file: (String path, *path_element path_elements) -> value
+
+  # A lazy view of one JSON container: children resolve on first
+  # access (containers as further Lazy nodes, scalars as values,
+  # misses as nil) and are cached on the node.
+  class Lazy
+    include Enumerable[untyped]
+
+    def []: (path_element token) -> (Lazy | value)
+
+    def dig: (path_element first, *path_element rest) -> (Lazy | value)
+
+    def at_pointer: (String pointer) -> (Lazy | value)
+
+    def value: () -> value
+
+    alias materialize value
+
+    def to_h: () -> Hash[String | Symbol, value]
+
+    def to_a: () -> Array[value]
+
+    def object?: () -> bool
+
+    def array?: () -> bool
+
+    def keys: () -> Array[String]
+
+    def size: () -> Integer
+
+    alias length size
+
+    alias count size
+
+    def empty?: () -> bool
+
+    def each: () { (untyped) -> void } -> self
+            | () -> Enumerator[untyped, self]
+
+    def inspect: () -> String
+
+    alias to_s inspect
+  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.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Yaroslav Markin
@@ -25,7 +25,9 @@ dependencies:
         version: 0.9.91
 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
+  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.'
 email:
 - yaroslav@markin.net
@@ -42,6 +44,7 @@ files:
 - README.md
 - ext/nosj/Cargo.toml
 - ext/nosj/extconf.rb
+- ext/nosj/src/files.rs
 - ext/nosj/src/gen/errors.rs
 - ext/nosj/src/gen/hash_iter.rs
 - ext/nosj/src/gen/keys.rs
@@ -49,6 +52,7 @@ files:
 - ext/nosj/src/gen/opts.rs
 - ext/nosj/src/gen/ruby.rs
 - ext/nosj/src/gen/walker.rs
+- ext/nosj/src/lazy.rs
 - ext/nosj/src/lib.rs
 - ext/nosj/src/parse.rs
 - ext/nosj/src/pointer.rs
@@ -56,6 +60,7 @@ files:
 - ext/nosj/src/state.rs
 - lib/nosj.rb
 - lib/nosj/json.rb
+- lib/nosj/lazy.rb
 - lib/nosj/multi_json.rb
 - lib/nosj/native.rb
 - lib/nosj/version.rb