nosj 0.1.0 → 0.2.0

data/ext/nosj/src/lazy.rs

@@ -0,0 +1,402 @@
+//! Lazy documents: `NOSJ.lazy` wraps a JSON document and resolves
+//! access on demand through the crate's pointer skipper. Every node is
+//! a byte span into a shared, immutable copy of the document; container
+//! children come back as further lazy nodes, scalars materialize
+//! immediately through the same sink machinery as a full parse. Nothing
+//! outside the touched path is ever parsed, so pulling a few fields out
+//! of a large document costs microseconds, not a full parse.
+//!
+//! Validation is as-you-go (the crate's skipper checks bracket balance
+//! over skipped content and fully validates resolved targets), so a
+//! malformed region raises when an access first walks it, not at
+//! `NOSJ.lazy` time.
+
+use std::sync::Arc;
+
+use magnus::typed_data::Obj;
+use magnus::value::ReprValue;
+use magnus::{DataTypeFunctions, Error, RArray, RString, Ruby, TypedData, Value};
+
+use crate::parse::{err, materialize, parse_native_opts, utf8_input, ParseNativeOpts};
+use crate::pointer::{path_to_pointer, push_escaped_token};
+use crate::state::PULL_STATE;
+
+/// The document bytes behind a node tree. A frozen Ruby source is
+/// borrowed zero-copy: freezing rules out mutation, and every node
+/// GC-marks the string with `rb_gc_mark` semantics, which both keeps it
+/// alive and pins it against compaction, so the captured pointer stays
+/// valid for as long as any node exists. Anything else is copied once.
+pub(crate) enum DocBytes {
+    Owned(Vec<u8>),
+    Frozen {
+        source: rb_sys::VALUE,
+        ptr: *const u8,
+        len: usize,
+    },
+    /// A read-only file mapping (`NOSJ.load_lazy_file`): pages never
+    /// touched are never read off disk. Concurrent modification of the
+    /// mapped file by another process is documented as unsupported
+    /// (the standard mmap caveat).
+    Mmap(memmap2::Mmap),
+}
+
+/// The shared document: stable bytes plus the parse options every
+/// materialization from this document uses.
+struct DocInner {
+    bytes: DocBytes,
+    opts: ParseNativeOpts,
+}
+
+// SAFETY: the bytes are immutable for the document's whole life (an
+// owned Vec, or a frozen Ruby string pinned and kept alive by every
+// node's GC mark), so cross-thread reads are plain shared reads; the
+// raw VALUE is only dereferenced by the GC mark, which runs at
+// safepoints (the ShadowHandle contract in state.rs). There is no
+// interior mutability anywhere in the type.
+unsafe impl Send for DocInner {}
+unsafe impl Sync for DocInner {}
+
+impl DocInner {
+    fn bytes(&self) -> &[u8] {
+        match &self.bytes {
+            DocBytes::Owned(v) => v,
+            // SAFETY: the source string is frozen (no mutation, no
+            // buffer reallocation) and pinned+kept alive by every
+            // node's GC mark; see DocBytes.
+            DocBytes::Frozen { ptr, len, .. } => unsafe { std::slice::from_raw_parts(*ptr, *len) },
+            DocBytes::Mmap(m) => m,
+        }
+    }
+}
+
+const KIND_OBJECT: u8 = b'{';
+const KIND_ARRAY: u8 = b'[';
+
+/// One lazy container node: a byte span into its document. Spans always
+/// come from the crate's resolver (token edges within the doc bytes),
+/// and never cross the Ruby boundary, so they cannot be forged from
+/// Ruby.
+#[derive(TypedData)]
+#[magnus(class = "NOSJ::Lazy", mark)]
+pub struct LazyNode {
+    doc: Arc<DocInner>,
+    start: usize,
+    end: usize,
+    kind: u8,
+}
+
+impl DataTypeFunctions for LazyNode {
+    fn mark(&self, marker: &magnus::gc::Marker) {
+        if let DocBytes::Frozen { source, .. } = self.doc.bytes {
+            use magnus::rb_sys::FromRawValue;
+            // SAFETY: the VALUE was a live, frozen string at node
+            // creation and this mark is what keeps it that way.
+            marker.mark(unsafe { Value::from_raw(source) });
+        }
+    }
+}
+
+impl LazyNode {
+    fn span(&self) -> &[u8] {
+        &self.doc.bytes()[self.start..self.end]
+    }
+}
+
+/// Wrap a resolved raw-value slice: containers become new lazy nodes,
+/// scalars materialize now. `sub` must be a subslice of `doc.bytes`.
+fn resolved_to_value(ruby: &Ruby, doc: &Arc<DocInner>, sub: &[u8]) -> Result<Value, Error> {
+    match sub.first().copied() {
+        Some(k) if k == KIND_OBJECT || k == KIND_ARRAY => {
+            let base = doc.bytes().as_ptr() as usize;
+            let start = sub.as_ptr() as usize - base;
+            let node = LazyNode {
+                doc: Arc::clone(doc),
+                start,
+                end: start + sub.len(),
+                kind: k,
+            };
+            let obj: Obj<LazyNode> = ruby.obj_wrap(node);
+            Ok(obj.as_value())
+        }
+        _ => materialize(ruby, sub, &doc.opts),
+    }
+}
+
+/// Resolve `pointer` within `node`'s span. Shared by `__get` and
+/// `__at_pointer`; both misses and negative-index paths return nil.
+fn resolve_in_span(ruby: &Ruby, node: &LazyNode, pointer: &str) -> Result<Value, Error> {
+    // Resolve first (one PULL_STATE borrow, slice borrows the doc, not
+    // the buffers), then materialize (which re-borrows internally).
+    let resolved = PULL_STATE.with(|cell| {
+        let mut state = cell.borrow_mut();
+        // SAFETY: doc bytes were coderange-gated at NOSJ.lazy creation,
+        // and spans lie on token edges, so the span is valid UTF-8.
+        unsafe { nosj::pointer_utf8_unchecked(node.span(), pointer, &mut state.bufs) }
+    });
+    match resolved {
+        Ok(None) => Ok(ruby.qnil().as_value()),
+        Ok(Some(sub)) => resolved_to_value(ruby, &node.doc, sub.as_bytes()),
+        Err(e) if matches!(e.kind, nosj::ErrorKind::InvalidPointer) => {
+            Err(Error::new(ruby.exception_arg_error(), e.to_string()))
+        }
+        Err(e) => Err(err(ruby, e.to_string())),
+    }
+}
+
+/// `NOSJ.lazy(source, opts)`: gate the encoding, copy the bytes, locate
+/// the root value. Container roots wrap as lazy nodes; a scalar root has
+/// nothing to defer and materializes immediately.
+///
+/// The root span is the input trimmed of surrounding whitespace; no
+/// byte of content is walked here (resolving via the "" pointer would
+/// bracket-skip the whole document just to find the same end), so
+/// malformation anywhere, including root-level trailing garbage,
+/// surfaces on first access, per the module's lazy-validation contract.
+pub fn lazy_native(
+    ruby: &Ruby,
+    _rb_self: Value,
+    data: RString,
+    opts: Value,
+) -> Result<Value, Error> {
+    let o = parse_native_opts(ruby, opts)?;
+    let input = utf8_input(ruby, &data)?;
+
+    // Frozen sources are borrowed zero-copy (see DocBytes); `data` is
+    // on the caller's machine stack, so it stays pinned through this
+    // call, and the node's mark takes over from the first GC on.
+    let bytes = if data.as_value().is_frozen() {
+        use magnus::rb_sys::AsRawValue;
+        DocBytes::Frozen {
+            source: data.as_raw(),
+            ptr: input.as_ptr(),
+            len: input.len(),
+        }
+    } else {
+        DocBytes::Owned(input.to_vec())
+    };
+    wrap_root(ruby, bytes, o)
+}
+
+/// Wrap document bytes as the root lazy value. Shared by `NOSJ.lazy`
+/// and `NOSJ.load_lazy_file`; the bytes must already be known UTF-8.
+pub(crate) fn wrap_root(
+    ruby: &Ruby,
+    bytes: DocBytes,
+    opts: ParseNativeOpts,
+) -> Result<Value, Error> {
+    const WS: [u8; 4] = *b" \t\n\r";
+    let doc = Arc::new(DocInner { bytes, opts });
+    let input = doc.bytes();
+    let Some(start) = input.iter().position(|b| !WS.contains(b)) else {
+        return Err(err(ruby, "unexpected end of input".into()));
+    };
+    let end = input.iter().rposition(|b| !WS.contains(b)).unwrap() + 1;
+    let sub = &doc.bytes()[start..end];
+    resolved_to_value(ruby, &doc, sub)
+}
+
+/// `__get(token)`: one path step. Integer tokens are JSON Pointer
+/// indices (negative ones resolve to nil, as in NOSJ.dig); String and
+/// Symbol tokens are keys, `~`/`/`-escaped.
+pub fn lazy_get(ruby: &Ruby, rb_self: Obj<LazyNode>, token: Value) -> Result<Value, Error> {
+    let mut ptr = String::new();
+    if let Some(int) = magnus::Integer::from_value(token) {
+        let idx = int.to_i64()?;
+        if idx < 0 {
+            return Ok(ruby.qnil().as_value());
+        }
+        ptr.push('/');
+        ptr.push_str(&idx.to_string());
+    } else if let Some(s) = RString::from_value(token) {
+        push_escaped_token(&mut ptr, &s.to_string()?);
+    } else if let Some(sym) = magnus::Symbol::from_value(token) {
+        push_escaped_token(&mut ptr, &sym.name()?);
+    } else {
+        return Err(Error::new(
+            ruby.exception_arg_error(),
+            "keys must be Strings, Symbols, or Integers",
+        ));
+    }
+    resolve_in_span(ruby, &rb_self, &ptr)
+}
+
+/// `__dig(path)`: the whole dig path fused into ONE pointer resolution
+/// within this node's span, instead of one resolve (and one cached
+/// node) per step. Semantics match `NOSJ.dig`: negative indices and
+/// steps into scalars resolve to nil.
+pub fn lazy_dig(ruby: &Ruby, rb_self: Obj<LazyNode>, path: RArray) -> Result<Value, Error> {
+    match path_to_pointer(ruby, path)? {
+        Some(ptr) => resolve_in_span(ruby, &rb_self, &ptr),
+        None => Ok(ruby.qnil().as_value()),
+    }
+}
+
+/// `__at_pointer(pointer)`: a full RFC 6901 pointer, resolved within
+/// this node's subtree.
+pub fn lazy_at_pointer(
+    ruby: &Ruby,
+    rb_self: Obj<LazyNode>,
+    pointer: RString,
+) -> Result<Value, Error> {
+    let ptr = pointer.to_string()?;
+    resolve_in_span(ruby, &rb_self, &ptr)
+}
+
+/// `__materialize`: the whole span as plain Ruby values, under the
+/// document's parse options.
+pub fn lazy_materialize(ruby: &Ruby, rb_self: Obj<LazyNode>) -> Result<Value, Error> {
+    materialize(ruby, rb_self.span(), &rb_self.doc.opts)
+}
+
+/// `__kind`: `:object` or `:array`.
+pub fn lazy_kind(ruby: &Ruby, rb_self: Obj<LazyNode>) -> magnus::Symbol {
+    match rb_self.kind {
+        KIND_OBJECT => ruby.to_symbol("object"),
+        _ => ruby.to_symbol("array"),
+    }
+}
+
+/// `__byte_size`: span length in bytes (cheap; used by #inspect).
+pub fn lazy_byte_size(_ruby: &Ruby, rb_self: Obj<LazyNode>) -> usize {
+    rb_self.end - rb_self.start
+}
+
+fn reader_err(ruby: &Ruby, e: nosj::ParseError) -> Error {
+    err(ruby, e.to_string())
+}
+
+/// `__keys`: the object's decoded keys, one Reader walk, values skipped.
+pub fn lazy_keys(ruby: &Ruby, rb_self: Obj<LazyNode>) -> Result<RArray, Error> {
+    if rb_self.kind != KIND_OBJECT {
+        return Err(Error::new(
+            ruby.exception_type_error(),
+            "keys on a JSON array",
+        ));
+    }
+    let out = ruby.ary_new();
+    PULL_STATE.with(|cell| -> Result<(), Error> {
+        let mut state = cell.borrow_mut();
+        // SAFETY: spans are valid UTF-8 (see resolve_in_span).
+        let mut r = unsafe { nosj::Reader::from_utf8_unchecked(rb_self.span(), &mut state.bufs) };
+        r.next_node().map_err(|e| reader_err(ruby, e))?;
+        let mut has = match r.object_first_key().map_err(|e| reader_err(ruby, e))? {
+            Some(k) => {
+                out.push(ruby.str_new(k))?;
+                true
+            }
+            None => false,
+        };
+        while has {
+            r.skip_value().map_err(|e| reader_err(ruby, e))?;
+            has = match r.object_next_key().map_err(|e| reader_err(ruby, e))? {
+                Some(k) => {
+                    out.push(ruby.str_new(k))?;
+                    true
+                }
+                None => false,
+            };
+        }
+        Ok(())
+    })?;
+    Ok(out)
+}
+
+/// `__size`: entry count (object pairs or array elements), one walk,
+/// nothing materialized.
+pub fn lazy_size(ruby: &Ruby, rb_self: Obj<LazyNode>) -> Result<usize, Error> {
+    PULL_STATE.with(|cell| {
+        let mut state = cell.borrow_mut();
+        // SAFETY: spans are valid UTF-8 (see resolve_in_span).
+        let mut r = unsafe { nosj::Reader::from_utf8_unchecked(rb_self.span(), &mut state.bufs) };
+        r.next_node().map_err(|e| reader_err(ruby, e))?;
+        let mut n = 0usize;
+        if rb_self.kind == KIND_OBJECT {
+            let mut has = r
+                .object_first_key()
+                .map_err(|e| reader_err(ruby, e))?
+                .is_some();
+            while has {
+                n += 1;
+                r.skip_value().map_err(|e| reader_err(ruby, e))?;
+                has = r
+                    .object_next_key()
+                    .map_err(|e| reader_err(ruby, e))?
+                    .is_some();
+            }
+        } else {
+            let mut has = r.array_first().map_err(|e| reader_err(ruby, e))?;
+            while has {
+                n += 1;
+                r.skip_value().map_err(|e| reader_err(ruby, e))?;
+                has = r.array_next().map_err(|e| reader_err(ruby, e))?;
+            }
+        }
+        Ok(n)
+    })
+}
+
+/// A child discovered during a container walk: a doc-relative span,
+/// plus the owned key for object entries (decoded keys borrow the
+/// reader's scratch, so they are copied out before phase two).
+struct ChildDesc {
+    key: Option<String>,
+    start: usize,
+    end: usize,
+}
+
+/// `__children`: every direct child in ONE walk. Objects yield
+/// `[key, child]` pairs, arrays yield children; containers wrap lazily,
+/// scalars materialize. Two phases so the Reader's buffer borrow ends
+/// before materialization re-borrows the thread state.
+pub fn lazy_children(ruby: &Ruby, rb_self: Obj<LazyNode>) -> Result<RArray, Error> {
+    let base = rb_self.doc.bytes().as_ptr() as usize;
+    let descs: Result<Vec<ChildDesc>, nosj::ParseError> = PULL_STATE.with(|cell| {
+        let mut state = cell.borrow_mut();
+        // SAFETY: spans are valid UTF-8 (see resolve_in_span).
+        let mut r = unsafe { nosj::Reader::from_utf8_unchecked(rb_self.span(), &mut state.bufs) };
+        r.next_node()?;
+        let mut out = Vec::new();
+        if rb_self.kind == KIND_OBJECT {
+            let mut key = r.object_first_key()?.map(String::from);
+            while let Some(k) = key {
+                let sub = r.skip_value()?;
+                let start = sub.as_ptr() as usize - base;
+                out.push(ChildDesc {
+                    key: Some(k),
+                    start,
+                    end: start + sub.len(),
+                });
+                key = r.object_next_key()?.map(String::from);
+            }
+        } else {
+            let mut has = r.array_first()?;
+            while has {
+                let sub = r.skip_value()?;
+                let start = sub.as_ptr() as usize - base;
+                out.push(ChildDesc {
+                    key: None,
+                    start,
+                    end: start + sub.len(),
+                });
+                has = r.array_next()?;
+            }
+        }
+        Ok(out)
+    });
+    let descs = descs.map_err(|e| reader_err(ruby, e))?;
+
+    let out = ruby.ary_new_capa(descs.len());
+    for d in descs {
+        let child = resolved_to_value(ruby, &rb_self.doc, &rb_self.doc.bytes()[d.start..d.end])?;
+        match d.key {
+            Some(k) => {
+                let pair = ruby.ary_new_capa(2);
+                pair.push(ruby.str_new(&k))?;
+                pair.push(child)?;
+                out.push(pair)?;
+            }
+            None => out.push(child)?,
+        }
+    }
+    Ok(out)
+}

data/ext/nosj/src/lib.rs

@@ -5,6 +5,10 @@
 //!   GVL-releasing indexed parse) plus shared option decoding and
 //!   input gating.
 //! - `pointer.rs`: partial parsing (dig, at_pointer, batch forms).
+//! - `lazy.rs`: lazy documents (NOSJ.lazy nodes resolving access on
+//!   demand over shared document bytes).
+//! - `files.rs`: file entry points (load_file, write_file, and the
+//!   mmap-backed load_lazy_file / at_pointer_file / dig_file).
 //! - `sink.rs`: the VALUE-building and validation sinks with their
 //!   interned-key caches.
 //! - `state.rs`: per-thread reusable state and the GC-marked value
@@ -12,7 +16,9 @@
 //! - `gen/`: generation (JSON.generate-compatible walker, options,
 //!   key cache, protect shims, error mapping).
 
+pub mod files;
 pub mod gen;
+pub mod lazy;
 pub mod parse;
 pub mod pointer;
 pub mod sink;
@@ -39,6 +45,30 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
         "at_pointers_native",
         method!(pointer::at_pointers_native, 3),
     )?;
+    module.define_singleton_method("lazy_native", method!(lazy::lazy_native, 2))?;
+    module.define_singleton_method("load_file_native", method!(files::load_file_native, 2))?;
+    module.define_singleton_method("write_file_native", method!(files::write_file_native, 3))?;
+    module.define_singleton_method(
+        "load_lazy_file_native",
+        method!(files::load_lazy_file_native, 2),
+    )?;
+    module.define_singleton_method(
+        "at_pointer_file_native",
+        method!(files::at_pointer_file_native, 3),
+    )?;
+    module.define_singleton_method("dig_file_native", method!(files::dig_file_native, 2))?;
+    let lazy_class = module.define_class("Lazy", ruby.class_object())?;
+    // Nodes are only born from NOSJ.lazy / lazy resolution.
+    lazy_class.undef_default_alloc_func();
+    lazy_class.define_method("__get", method!(lazy::lazy_get, 1))?;
+    lazy_class.define_method("__dig", method!(lazy::lazy_dig, 1))?;
+    lazy_class.define_method("__at_pointer", method!(lazy::lazy_at_pointer, 1))?;
+    lazy_class.define_method("__materialize", method!(lazy::lazy_materialize, 0))?;
+    lazy_class.define_method("__kind", method!(lazy::lazy_kind, 0))?;
+    lazy_class.define_method("__byte_size", method!(lazy::lazy_byte_size, 0))?;
+    lazy_class.define_method("__keys", method!(lazy::lazy_keys, 0))?;
+    lazy_class.define_method("__size", method!(lazy::lazy_size, 0))?;
+    lazy_class.define_method("__children", method!(lazy::lazy_children, 0))?;
     module.define_singleton_method("generate_native", method!(gen::generate_native, 2))?;
     // `generate` itself is native and variadic: the json gem routes
     // its `generate` through a Ruby frame into C, so skipping our own

data/ext/nosj/src/pointer.rs

@@ -49,21 +49,23 @@ pub fn at_pointer_native(
     at_pointer_impl(ruby, data, &ptr, &o)
 }
 
-/// Convert one dig path (String/Symbol keys, Integer indices) into a
-/// JSON Pointer, `~`/`/` escaped. `None` = a negative index: no pointer
-/// equivalent, the path resolves to `nil` by definition.
-fn path_to_pointer(ruby: &Ruby, path: magnus::RArray) -> Result<Option<String>, Error> {
-    fn push_escaped_token(ptr: &mut String, key: &str) {
-        ptr.push('/');
-        for c in key.chars() {
-            match c {
-                '~' => ptr.push_str("~0"),
-                '/' => ptr.push_str("~1"),
-                c => ptr.push(c),
-            }
+/// Append one RFC 6901 reference token (`/` prefix, `~`/`/` escaped).
+/// Shared with the lazy-document single-step resolver.
+pub(crate) fn push_escaped_token(ptr: &mut String, key: &str) {
+    ptr.push('/');
+    for c in key.chars() {
+        match c {
+            '~' => ptr.push_str("~0"),
+            '/' => ptr.push_str("~1"),
+            c => ptr.push(c),
         }
     }
+}
 
+/// Convert one dig path (String/Symbol keys, Integer indices) into a
+/// JSON Pointer. `None` = a negative index: no pointer equivalent, the
+/// path resolves to `nil` by definition. Shared with `NOSJ::Lazy#dig`.
+pub(crate) fn path_to_pointer(ruby: &Ruby, path: magnus::RArray) -> Result<Option<String>, Error> {
     let mut ptr = String::new();
     for i in 0..path.len() {
         let item: Value = path.entry(i as isize)?;

data/lib/nosj/lazy.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module NOSJ
+  # A lazy view of one JSON container inside a document created with
+  # {NOSJ.lazy}. Nothing is parsed until it is touched: indexing walks
+  # the raw bytes to the requested child (skipping siblings at SIMD
+  # block speed), returns another Lazy node for containers, and
+  # materializes plain Ruby values for scalars. Resolved children are
+  # cached, so repeated access is free and object identity is stable.
+  #
+  # Validation is as-you-go: skipped content is bracket-balance
+  # checked and resolved targets fully validated, so a malformed region
+  # raises when an access first walks it, not at {NOSJ.lazy} time.
+  #
+  # Nodes hold their own stable copy of the document (shared across the
+  # whole node tree), so mutating the source string later is harmless.
+  #
+  # @example Pull two fields out of a big document
+  #   doc = NOSJ.lazy(huge_json)
+  #   doc["users"][3]["name"]     # only this path is parsed
+  #   doc.dig("meta", "count")
+  #
+  # @example Materialize a subtree
+  #   doc["users"][3].value       #=> {"name" => ..., ...}
+  class Lazy
+    include Enumerable
+
+    # Resolves one child. String and Symbol keys index objects; Integer
+    # indices index arrays (negative indices resolve to +nil+, as in
+    # {NOSJ.dig}). Containers come back as further Lazy nodes, scalars
+    # as plain Ruby values, misses as +nil+. Results are cached on the
+    # node.
+    #
+    # @param token [String, Symbol, Integer]
+    # @return [NOSJ::Lazy, Object, nil]
+    def [](token)
+      cache = (@children ||= {})
+      cache.fetch(token) { cache[token] = __get(token) }
+    end
+
+    # Hash#dig-shaped access, fused into a single resolution: the whole
+    # path resolves in one walk of this node's bytes, no intermediate
+    # nodes. Semantics match {NOSJ.dig}: misses, negative indices, and
+    # steps into scalars resolve to +nil+. Not cached.
+    #
+    # @param path [Array<String, Symbol, Integer>]
+    # @return [NOSJ::Lazy, Object, nil]
+    def dig(first, *rest)
+      __dig([first, *rest])
+    end
+
+    # Resolves an RFC 6901 JSON Pointer within this node's subtree,
+    # with the same lazy/materialize behavior as {#[]}. Not cached.
+    #
+    # @param pointer [String] e.g. <tt>"/users/3/name"</tt>
+    # @return [NOSJ::Lazy, Object, nil]
+    def at_pointer(pointer)
+      __at_pointer(pointer)
+    end
+
+    # Materializes this node's whole subtree as plain Ruby values,
+    # under the options given to {NOSJ.lazy} (+symbolize_names+,
+    # +freeze+, ...).
+    #
+    # @return [Hash, Array]
+    def value
+      __materialize
+    end
+    alias_method :materialize, :value
+
+    # @return [Hash] the materialized subtree
+    # @raise [TypeError] on an array node
+    def to_h
+      raise TypeError, "to_h on a JSON array" unless object?
+
+      __materialize
+    end
+
+    # @return [Array] the materialized subtree
+    # @raise [TypeError] on an object node
+    def to_a
+      raise TypeError, "to_a on a JSON object" unless array?
+
+      __materialize
+    end
+
+    # @return [Boolean] whether this node is a JSON object
+    def object?
+      __kind == :object
+    end
+
+    # @return [Boolean] whether this node is a JSON array
+    def array?
+      __kind == :array
+    end
+
+    # The object's keys (always Strings), read in one walk without
+    # materializing any values.
+    #
+    # @return [Array<String>]
+    # @raise [TypeError] on an array node
+    def keys
+      __keys
+    end
+
+    # Entry count (object pairs or array elements), read in one walk
+    # without materializing anything.
+    #
+    # @return [Integer]
+    def size
+      __size
+    end
+    alias_method :length, :size
+    alias_method :count, :size
+
+    # @return [Boolean]
+    def empty?
+      size.zero?
+    end
+
+    # Iterates direct children, resolved in one walk: object nodes
+    # yield +[key, child]+ pairs (like Hash), array nodes yield
+    # children. Containers arrive as Lazy nodes, scalars as values.
+    #
+    # @return [Enumerator] when no block is given
+    def each(&block)
+      return enum_for(:each) unless block
+
+      if object?
+        __children.each { |pair| yield pair }
+      else
+        __children.each { |child| yield child }
+      end
+      self
+    end
+
+    # @return [String] kind and span size, without touching content
+    def inspect
+      "#<NOSJ::Lazy #{__kind} (#{__byte_size} bytes)>"
+    end
+    alias_method :to_s, :inspect
+
+    private :__get, :__dig, :__at_pointer, :__materialize, :__kind,
+      :__byte_size, :__keys, :__size, :__children
+  end
+
+  # Wraps a JSON document for lazy, on-demand access: returns a
+  # {NOSJ::Lazy} node for a container root, or the materialized value
+  # for a scalar root. The document bytes are copied once; no parsing
+  # happens beyond locating the root value.
+  #
+  # @example
+  #   doc = NOSJ.lazy('{"users":[{"name":"ada"},{"name":"grace"}]}')
+  #   doc["users"][1]["name"]  #=> "grace" — the rest is never parsed
+  #
+  # @param source [String] the JSON document (UTF-8 or US-ASCII)
+  # @param opts [Hash, nil] {NOSJ.parse} options applied whenever a
+  #   value materializes: +symbolize_names+, +freeze+, +max_nesting+,
+  #   +allow_nan+, +allow_trailing_comma+
+  # @return [NOSJ::Lazy, Object]
+  # @raise [RuntimeError] when the document root is malformed
+  def self.lazy(source, opts = nil)
+    lazy_native(source, opts)
+  end
+end

data/lib/nosj/version.rb

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