Decodes complete JSON values, opens binary or native file-backed documents, selects scalar values, and lazily streams projected rows using SIMD-accelerated parsing.

select/2 extracts several named scalar paths from either a JSON binary or a caller-owned document. Results use the exact atom or binary keys supplied by the caller. Object and array leaves are deliberately not materialized.

A document belongs to the process that opened it. Owner close/1 is idempotent and waits for native cleanup; another process receives a stable :not_owner error even when the document has already been closed. Projection is one-shot: after native cursor access begins, success or failure consumes the document. Use another document, or call select/2 with the binary again, for another projection.

Projection grammar errors are tagged :invalid_projection. Values that are not binaries or genuine document resources raise ArgumentError. Other parsing, path, ownership, lifecycle, allocation, and cancellation failures return {:error, %SimdJson.Error{}} without a partial result. Selected strings are fresh binaries independent of their source.

Decode accepts binaries and an empty option list only. Its bang wrapper is Elixir-only and raises the same structured error returned by decode/2. Eager decode allocates the complete value; prefer projection or streaming for large inputs when only a subset is needed.

For large files, open_file/1, select_file/2, and stream_file/2 pass only the path through the BEAM boundary. File streaming delegates the memory map, fixed parser windows, document iteration, and projection batching to simdjson; do not wrap these calls in File.read/1.

The API intentionally has no projection bang variant, JSONPath, wildcard, default-field policy, public compiled plan, raw cursor/batch operation, ownership transfer, or native-handle operation.

All native execution uses a fixed bounded worker pool. Queue saturation returns a redacted :busy error. The qualified target is Ubuntu 24.04 x86-64.

Examples

iex> SimdJson.decode(~s({"ready":true}))
{:ok, %{"ready" => true}}
iex> SimdJson.decode("[1,2,3]", [])
{:ok, [1, 2, 3]}
iex> SimdJson.decode!(~s("hello"))
"hello"
iex> SimdJson.decode!("null", [])
nil

iex> {:ok, document} = SimdJson.open(~s({"ready": true}))
iex> inspect(document)
"#SimdJson.Document<opaque>"
iex> SimdJson.close(document)
:ok
iex> SimdJson.close(document)
:ok

iex> json = ~s({"customer":{"id":7,"name":"Acme"},"orders":[{"sku":"A-1"}]})
iex> projection = [{:id, ["customer", "id"]}, {"sku", ["orders", 0, "sku"]}]
iex> SimdJson.select(json, projection)
{:ok, %{"sku" => "A-1", id: 7}}

iex> {:ok, document} = SimdJson.open(~s({"value":42}))
iex> SimdJson.select(document, value: ["value"])
{:ok, %{value: 42}}
iex> {:error, consumed} = SimdJson.select(document, value: ["value"])
iex> consumed.reason
:cursor_consumed
iex> SimdJson.close(document)
:ok

iex> {:error, missing} = SimdJson.select(~s({"ready":true}), value: ["value"])
iex> {missing.reason, missing.path}
{:no_such_field, ["value"]}
iex> inspect(missing) =~ "value"
false

iex> {:error, type_error} = SimdJson.select(~s({"items":[]}), items: ["items"])
iex> type_error.reason
:incorrect_type

iex> {:error, invalid} = SimdJson.select("not inspected", [])
iex> {invalid.reason, invalid.byte_offset, invalid.path}
{:invalid_projection, nil, nil}

iex> source = ~s({"selected":"small","ignored":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"})
iex> {:ok, %{selected: selected}} = SimdJson.select(source, selected: ["selected"])
iex> source = nil
iex> :erlang.garbage_collect(self())
iex> {source, selected}
{nil, "small"}

iex> function_exported?(SimdJson, :select!, 2)
false
iex> Code.ensure_loaded?(SimdJson.CompiledProjection)
false

iex> {:error, error} = SimdJson.open("[1,")
iex> {error.reason, error.message}
{:unexpected_eof, "unexpected end of JSON input"}
iex> inspect(error) =~ "[1,"
false

iex> SimdJson.open(:not_a_binary)
** (ArgumentError) expected JSON input to be a binary

iex> {:ok, document} = SimdJson.open("null")
iex> task = Task.async(fn -> SimdJson.close(document) end)
iex> {:error, non_owner_error} = Task.await(task)
iex> non_owner_error.reason
:not_owner
iex> SimdJson.close(document)
:ok