Merge pull request #34 from lpgauth/compiled-pointers

Add compiled pointers and fused parse_get_many_nil

Author: lpgauth

CLAUDE.md

@@ -72,7 +72,9 @@ Torque is a high-performance JSON library for Elixir using Rustler NIFs backed b
 
 1. **Parse + Get** — `parse/1` returns an opaque reference to a parsed document (`sonic_rs::Value`). `get/2,3` extracts fields by JSON Pointer (RFC 6901) path via `value_to_term`. `get_many/2` extracts multiple fields in a single NIF call. Ideal when only a subset of fields is needed.
 
-2. **Full decode** — `decode/1` builds Erlang terms directly during the SIMD parse by implementing sonic-rs's native `JsonVisitor` (`native_decode.rs`): single pass, no intermediate `Value`, zero-copy sub-binaries for unescaped strings.
+2. **Compiled pointers** — for a *fixed* set of paths extracted from every document, `compile_pointers/2` pre-parses the pointer strings once into a `CompiledPaths` resource (`PathSeg::Key` / `PathSeg::Num{idx,key}`, with `~`-unescaping and array-index-vs-object-key resolution done up front). `parse_get_many_nil/2` then fuses the DOM parse and extraction into one NIF call (no document handle, no second boundary crossing), returning `{:ok, values}` with `nil` for missing/`null`. The handle carries the `unique_keys` lookup strategy. ~1.5× faster end-to-end than `parse/2` + `get_many_nil/2` on a typical field set; `get_many_nil/2` also accepts a compiled handle to query an already-parsed doc. Note: a lazy single-pass approach (sonic-rs `get_many` over a `PointerTree`) was measured ~6× *slower* here — per-call `PointerTree` (HashMap + `FastStr`) construction dominates — so the DOM is the right structure for this small-doc / many-short-paths workload.
+
+3. **Full decode** — `decode/1` builds Erlang terms directly during the SIMD parse by implementing sonic-rs's native `JsonVisitor` (`native_decode.rs`): single pass, no intermediate `Value`, zero-copy sub-binaries for unescaped strings.
 
 ### Encoding
 
@@ -98,8 +100,8 @@ Inputs larger than 20 KB are automatically dispatched to dirty CPU schedulers to
 
 - `lib/torque.ex` — public API with `@doc`, typespecs, dirty scheduler dispatch
 - `lib/torque/native.ex` — RustlerPrecompiled NIF stubs (set `TORQUE_BUILD=true` to compile from source)
-- `native/torque_nif/src/lib.rs` — NIF registration, `ParsedDocument` resource
-- `native/torque_nif/src/decoder.rs` — parse, get, get_many, decode NIFs
+- `native/torque_nif/src/lib.rs` — NIF registration, `ParsedDocument` + `CompiledPaths` (`PathSeg`) resources
+- `native/torque_nif/src/decoder.rs` — parse, get, get_many, get_many_nil, decode NIFs; compiled-pointer + fused `parse_get_many_nil` path
 - `native/torque_nif/src/native_decode.rs` — fused decoder; builds terms during the SIMD parse via sonic-rs's `JsonVisitor`
 - `native/torque_nif/src/encoder.rs` — direct term-walking JSON encoder
 - `native/torque_nif/src/types.rs` — sonic_rs Value → Erlang term conversion (used by get/get_many)

README.md

@@ -10,6 +10,7 @@ Torque provides the fastest JSON encoding and decoding available in the BEAM eco
 - Ultra-low memory encoder (64 B per encode vs ~4 KB for OTP `json`/jason)
 - Parse-then-get API for selective field extraction via JSON Pointer (RFC 6901)
 - Batch field extraction (`get_many/2`) with single NIF call
+- Pre-compiled pointers with fused parse + extract (`parse_get_many_nil/2`)
 - Automatic dirty CPU scheduler dispatch for inputs larger than 20 KB
 - jiffy-compatible `{proplist}` encoding
 
@@ -78,6 +79,24 @@ for faster field lookups (uses sonic-rs internal indexing instead of linear scan
 {:ok, doc} = Torque.parse(json, unique_keys: true)
 ```
 
+### Compiled Pointers
+
+When the same fixed set of paths is extracted from every document, compile the
+pointers once and reuse the handle. `parse_get_many_nil/2` then fuses the parse
+and extraction into a single NIF call, skipping all per-request path parsing —
+roughly 1.5× faster end-to-end than `parse/2` + `get_many_nil/2`.
+
+```elixir
+# Once, at startup (e.g. a module attribute or :persistent_term):
+pointers = Torque.compile_pointers(["/id", "/site/domain", "/imp/0/banner/w"], unique_keys: true)
+
+# Per document — parse + extract in one call:
+{:ok, ["req-1", "example.com", 300]} = Torque.parse_get_many_nil(json, pointers)
+```
+
+Missing fields and JSON `null` both become `nil`. The handle also works with an
+already-parsed document via `Torque.get_many_nil(doc, pointers)`.
+
 ### Encoding
 
 ```elixir
@@ -99,17 +118,19 @@ json = Torque.encode_to_iodata(%{id: "abc"})
 
 | Function | Description |
 |----------|-------------|
+| `Torque.compile_pointers(paths, opts)` | Pre-compile a fixed path set into a reusable handle |
 | `Torque.decode(binary)` | Decode JSON to Elixir terms |
 | `Torque.decode!(binary)` | Decode JSON, raising on error |
-| `Torque.parse(binary, opts)` | Parse JSON into opaque document reference |
+| `Torque.encode(term)` | Encode term to JSON binary |
+| `Torque.encode!(term)` | Encode term, raising on error |
+| `Torque.encode_to_iodata(term)` | Encode term, returns binary directly (fastest) |
 | `Torque.get(doc, path)` | Extract field by JSON Pointer path |
 | `Torque.get(doc, path, default)` | Extract field with default for missing paths |
 | `Torque.get_many(doc, paths)` | Extract multiple fields in one NIF call |
 | `Torque.get_many_nil(doc, paths)` | Extract multiple fields, `nil` for missing |
 | `Torque.length(doc, path)` | Return length of array at path |
-| `Torque.encode(term)` | Encode term to JSON binary |
-| `Torque.encode!(term)` | Encode term, raising on error |
-| `Torque.encode_to_iodata(term)` | Encode term, returns binary directly (fastest) |
+| `Torque.parse(binary, opts)` | Parse JSON into opaque document reference |
+| `Torque.parse_get_many_nil(binary, pointers)` | Fused parse + extract of compiled pointers in one NIF call |
 
 ## Type Conversion
 
@@ -151,9 +172,9 @@ Functions return `{:error, reason}` tuples (or raise `ArgumentError` for bang/io
 
 | Atom | Returned by | Meaning |
 |------|-------------|---------|
-| `:nesting_too_deep` | `decode/1`, `parse/1`, `get/2`, `get_many/2` | Document exceeds 128 nesting levels |
+| `:nesting_too_deep` | `decode/1`, `parse/1`, `get/2`, `get_many/2`, `parse_get_many_nil/2` | Document exceeds 128 nesting levels |
 
-`parse/1` and `decode/1` also return `{:error, binary}` with a message from sonic-rs for malformed JSON.
+`parse/1`, `decode/1`, and `parse_get_many_nil/2` also return `{:error, binary}` with a message from sonic-rs for malformed JSON.
 
 ### Encode
 

lib/torque.ex

@@ -9,6 +9,12 @@ defmodule Torque do
       by JSON Pointer (RFC 6901) paths without materializing the full
       Elixir term tree. Ideal when only a subset of fields is needed.
 
+    * **Compiled pointers** — when the same fixed set of paths is extracted
+      from every document, `compile_pointers/2` pre-parses the paths once and
+      `parse_get_many_nil/2` fuses the parse and extraction into a single NIF
+      call. Skips all per-request path parsing — roughly 1.5× faster end-to-end
+      than `parse/2` + `get_many_nil/2`.
+
     * **Full decode** — `decode/1` converts an entire JSON binary into
       Elixir terms in one pass.
 
@@ -41,6 +47,13 @@ defmodule Torque do
 
   @timeslice_bytes 20_480
 
+  @typedoc """
+  An opaque handle to a set of pre-compiled JSON Pointer paths, returned by
+  `compile_pointers/2`. Pass it to `parse_get_many_nil/2` or `get_many_nil/2`
+  in place of a path list to skip per-call path parsing.
+  """
+  @opaque pointers :: reference()
+
   # --- Decoding ---
 
   @doc """
@@ -289,18 +302,102 @@ defmodule Torque do
   Faster than `get_many/2` when you don't need to distinguish between
   missing fields and null values, as it avoids allocating wrapper tuples.
 
+  Accepts either a list of JSON Pointer path strings or a `t:pointers/0` handle
+  built by `compile_pointers/2`. The compiled form skips all per-call path
+  parsing and is the recommended option for a fixed, repeatedly-queried path
+  set.
+
   ## Examples
 
       iex> {:ok, doc} = Torque.parse(~s({"a":1,"b":null}))
       iex> Torque.get_many_nil(doc, ["/a", "/b", "/c"])
       [1, nil, nil]
+
+      iex> {:ok, doc} = Torque.parse(~s({"a":1,"b":null}))
+      iex> ptrs = Torque.compile_pointers(["/a", "/b", "/c"])
+      iex> Torque.get_many_nil(doc, ptrs)
+      [1, nil, nil]
   """
   @doc group: :parse_get
-  @spec get_many_nil(reference(), [binary()]) :: [term()]
+  @spec get_many_nil(reference(), [binary()] | pointers()) :: [term()]
   def get_many_nil(doc, paths) when is_reference(doc) and is_list(paths) do
     Torque.Native.get_many_nil(doc, paths)
   end
 
+  def get_many_nil(doc, pointers) when is_reference(doc) and is_reference(pointers) do
+    Torque.Native.get_many_nil_compiled(doc, pointers)
+  end
+
+  @doc """
+  Pre-compiles a list of JSON Pointer paths into a reusable handle.
+
+  Workloads that parse many documents and extract the *same* fixed set of fields
+  re-split and unescape those pointer strings on every call — wasted work, since
+  they never change. `compile_pointers/2` does it once and returns an opaque
+  `t:pointers/0` handle that `parse_get_many_nil/2` and `get_many_nil/2` accept
+  in place of a path list, eliminating all per-call path parsing (≈2× faster
+  extraction on a typical field set).
+
+  Compile once at startup (e.g. into a module attribute or `:persistent_term`)
+  and reuse the handle for every document.
+
+  ## Options
+
+    * `:unique_keys` — when `true`, object key lookups use a forward scan that
+      stops at the first match (faster). Defaults to `false` (reverse scan,
+      last-value-wins for duplicate keys), matching `parse/2`. Safe to enable
+      when keys are known to be unique.
+
+  Extraction results are returned in the same order as `paths`.
+
+  ## Examples
+
+      iex> ptrs = Torque.compile_pointers(["/a", "/b/0"], unique_keys: true)
+      iex> {:ok, doc} = Torque.parse(~s({"a":1,"b":[2,3]}))
+      iex> Torque.get_many_nil(doc, ptrs)
+      [1, 2]
+  """
+  @doc group: :parse_get
+  @spec compile_pointers([binary()], keyword()) :: pointers()
+  def compile_pointers(paths, opts \\ []) when is_list(paths) do
+    Torque.Native.compile_paths(paths, Keyword.get(opts, :unique_keys, false))
+  end
+
+  @doc """
+  Parses a JSON binary and extracts pre-compiled pointers in a single NIF call.
+
+  Fuses `parse/2` and `get_many_nil/2` for the common parse-once-extract-once
+  case: it parses the document, extracts each compiled pointer, and returns the
+  values — without materializing a reusable document handle or crossing the NIF
+  boundary twice. Missing fields and JSON `null` both become `nil`. The lookup
+  strategy (`:unique_keys`) is taken from the `t:pointers/0` handle.
+
+  Returns `{:ok, values}` (in the same order as the paths given to
+  `compile_pointers/2`) or `{:error, reason}` if the JSON is malformed.
+  Automatically uses a dirty CPU scheduler for inputs larger than 20 KB.
+
+  ## Examples
+
+      iex> ptrs = Torque.compile_pointers(["/id", "/site/domain", "/missing"])
+      iex> Torque.parse_get_many_nil(~s({"id":"x","site":{"domain":"e.com"}}), ptrs)
+      {:ok, ["x", "e.com", nil]}
+
+      iex> ptrs = Torque.compile_pointers(["/a"])
+      iex> match?({:error, _}, Torque.parse_get_many_nil("not json", ptrs))
+      true
+  """
+  @doc group: :parse_get
+  @spec parse_get_many_nil(binary(), pointers()) ::
+          {:ok, [term()]} | {:error, binary() | :nesting_too_deep}
+  def parse_get_many_nil(json, pointers)
+      when is_binary(json) and is_reference(pointers) and byte_size(json) > @timeslice_bytes do
+    Torque.Native.parse_get_many_nil_dirty(json, pointers)
+  end
+
+  def parse_get_many_nil(json, pointers) when is_binary(json) and is_reference(pointers) do
+    Torque.Native.parse_get_many_nil(json, pointers)
+  end
+
   @doc """
   Extracts multiple values from a parsed document with per-path defaults.
 

lib/torque/native.ex

@@ -38,5 +38,9 @@ defmodule Torque.Native do
   def encode(_term), do: :erlang.nif_error(:nif_not_loaded)
   def encode_iodata(_term), do: :erlang.nif_error(:nif_not_loaded)
   def get_many_nil(_doc, _paths), do: :erlang.nif_error(:nif_not_loaded)
+  def compile_paths(_paths, _unique_keys), do: :erlang.nif_error(:nif_not_loaded)
+  def get_many_nil_compiled(_doc, _compiled), do: :erlang.nif_error(:nif_not_loaded)
+  def parse_get_many_nil(_json, _compiled), do: :erlang.nif_error(:nif_not_loaded)
+  def parse_get_many_nil_dirty(_json, _compiled), do: :erlang.nif_error(:nif_not_loaded)
   def array_length(_doc, _path), do: :erlang.nif_error(:nif_not_loaded)
 end

mix.exs

@@ -1,7 +1,7 @@
 defmodule Torque.MixProject do
   use Mix.Project
 
-  @version "0.2.3"
+  @version "0.2.4"
   @source_url "https://github.com/lpgauth/torque"
 
   def project do

native/torque_nif/src/decoder.rs

@@ -297,6 +297,158 @@ fn decode_dirty<'a>(env: Env<'a>, json: Binary<'a>) -> Term<'a> {
     native_decode::decode_to_term(env, input_term, json.as_slice())
 }
 
+// --- Pre-compiled pointers + fused parse/extract ---
+//
+// The common parse-once-extract-once workload uses a *fixed* set of JSON
+// Pointer paths known at startup. Compiling those paths once (segment split,
+// `~`-unescape, index-vs-key classification) lets the per-request call skip all
+// per-path string work — roughly halving extraction time — and fusing the parse
+// and the extraction into one NIF call avoids materializing a document handle.
+use crate::{CompiledPaths, PathSeg};
+
+/// Pre-split a single JSON Pointer into segments. A numeric segment is stored as
+/// `Num`, keeping both the parsed index and the literal key so the lookup can
+/// pick the right interpretation per node (array index vs. object key) —
+/// matching the runtime behaviour of `pointer_lookup`.
+fn compile_one(path: &str) -> Vec<PathSeg> {
+    let mut segs = Vec::new();
+    if path.len() <= 1 {
+        return segs;
+    }
+    for segment in path[1..].split('/') {
+        let b = segment.as_bytes();
+        let key = if segment.contains('~') {
+            segment.replace("~1", "/").replace("~0", "~")
+        } else {
+            segment.to_string()
+        };
+        if !b.is_empty() && b[0].is_ascii_digit() {
+            if let Ok(idx) = segment.parse::<usize>() {
+                segs.push(PathSeg::Num { idx, key });
+                continue;
+            }
+        }
+        segs.push(PathSeg::Key(key));
+    }
+    segs
+}
+
+#[rustler::nif]
+fn compile_paths<'a>(env: Env<'a>, paths: ListIterator<'a>, unique_keys: bool) -> Term<'a> {
+    let mut out = Vec::new();
+    for pt in paths {
+        let p: &str = pt.decode().unwrap_or("");
+        out.push(compile_one(p));
+    }
+    ResourceArc::new(CompiledPaths {
+        paths: out,
+        unique_keys,
+    })
+    .encode(env)
+}
+
+/// Extract all compiled paths from an already-traversed `value` into a result
+/// list term, substituting nil for missing fields and depth-exceeded values.
+#[inline]
+fn extract_compiled<'a>(
+    env: Env<'a>,
+    value: &sonic_rs::Value,
+    compiled: &CompiledPaths,
+) -> Term<'a> {
+    let nil_raw = atoms::nil().as_c_arg();
+    let n = compiled.paths.len();
+    let mut stack: [ERL_NIF_TERM; GET_MANY_STACK] = [0; GET_MANY_STACK];
+    let mut heap: Option<Vec<ERL_NIF_TERM>> = if n > GET_MANY_STACK {
+        Some(Vec::with_capacity(n))
+    } else {
+        None
+    };
+    for (i, segs) in compiled.paths.iter().enumerate() {
+        let r = match pointer_lookup_compiled(value, segs, compiled.unique_keys) {
+            Some(v) => value_to_term(env, v, MAX_DEPTH)
+                .map(|t| t.as_c_arg())
+                .unwrap_or(nil_raw),
+            None => nil_raw,
+        };
+        match &mut heap {
+            Some(v) => v.push(r),
+            None => stack[i] = r,
+        }
+    }
+    let terms = match &heap {
+        Some(v) => v.as_slice(),
+        None => &stack[..n],
+    };
+    unsafe {
+        Term::new(
+            env,
+            enif_make_list_from_array(env.as_c_arg(), terms.as_ptr(), n as u32),
+        )
+    }
+}
+
+#[inline]
+fn do_parse_get_many_nil<'a>(env: Env<'a>, bytes: &[u8], compiled: &CompiledPaths) -> Term<'a> {
+    match sonic_rs::from_slice::<sonic_rs::Value>(bytes) {
+        Ok(value) => {
+            let list = extract_compiled(env, &value, compiled);
+            make_tuple2(env, atoms::ok().as_c_arg(), list.as_c_arg())
+        }
+        Err(e) => parse_error_term(env, format!("{}", e)),
+    }
+}
+
+#[rustler::nif]
+fn parse_get_many_nil<'a>(
+    env: Env<'a>,
+    json: Binary,
+    compiled: ResourceArc<CompiledPaths>,
+) -> Term<'a> {
+    let result = do_parse_get_many_nil(env, json.as_slice(), &compiled);
+    schedule::consume_timeslice(env, timeslice_percent(json.len()));
+    result
+}
+
+#[rustler::nif(schedule = "DirtyCpu")]
+fn parse_get_many_nil_dirty<'a>(
+    env: Env<'a>,
+    json: Binary,
+    compiled: ResourceArc<CompiledPaths>,
+) -> Term<'a> {
+    do_parse_get_many_nil(env, json.as_slice(), &compiled)
+}
+
+#[inline]
+fn pointer_lookup_compiled<'v>(
+    value: &'v sonic_rs::Value,
+    segs: &[PathSeg],
+    unique_keys: bool,
+) -> Option<&'v sonic_rs::Value> {
+    let mut current = value;
+    for seg in segs {
+        current = match seg {
+            PathSeg::Key(k) => object_get(current, k, unique_keys)?,
+            PathSeg::Num { idx, key } => {
+                if current.is_array() {
+                    current.get(*idx)?
+                } else {
+                    object_get(current, key, unique_keys)?
+                }
+            }
+        };
+    }
+    Some(current)
+}
+
+#[rustler::nif]
+fn get_many_nil_compiled<'a>(
+    env: Env<'a>,
+    doc: ResourceArc<ParsedDocument>,
+    compiled: ResourceArc<CompiledPaths>,
+) -> Term<'a> {
+    extract_compiled(env, &doc.value, &compiled)
+}
+
 #[rustler::nif]
 fn get_many_nil<'a>(
     env: Env<'a>,