Jexata (jexata v1.0.0)

Compile JSONata expressions and evaluate them against native Elixir values.

See README.md and docs/COMPATIBILITY.md for supported syntax and known gaps.

Summary

Functions

compile(source, options \\ [])

Compiles a JSONata source string into an immutable expression.

compile!(source)

Like compile/1, but raises on errors.

evaluate(expression, data)

Evaluates a compiled expression against JSON-like Elixir data.

evaluate(arg1, data, bindings)

Evaluates a compiled expression with external variable bindings.

evaluate(arg1, data, bindings, options)

Evaluates with a positive :max_function_depth limit for recursive calls.

evaluate!(expression, data)

Like evaluate/2, but raises on errors.

evaluate_bounded(expression, data, options \\ [])

Evaluates in a separate BEAM process with time, heap, reductions, and result-size limits.

run(source, data)

Compiles and evaluates a JSONata expression in one call.

run(source, data, bindings)

Compiles and evaluates an expression with external variable bindings.

run(source, data, bindings, options)

Compiles and evaluates with external bindings and evaluation options.

run!(source, data)

Like run/2, but raises on errors.

Types

input()

@type input() :: json() | :undefined

json()

@type json() ::
  nil
  | boolean()
  | number()
  | String.t()
  | [json()]
  | %{optional(String.t()) => json()}

result()

@type result() :: json() | :undefined | :function

Functions

compile(source, options \\ [])

@spec compile(String.t(), keyword()) ::
  {:ok, Jexata.Expression.t()} | {:error, Jexata.Error.t()}

Compiles a JSONata source string into an immutable expression.

max_source_bytes, max_tokens, and max_nesting may be set as positive integers.

compile!(source)

@spec compile!(String.t()) :: Jexata.Expression.t()

Like compile/1, but raises on errors.

evaluate(expression, data)

@spec evaluate(Jexata.Expression.t(), input()) ::
  {:ok, result()} | {:error, Jexata.Error.t()}

Evaluates a compiled expression against JSON-like Elixir data.

evaluate(arg1, data, bindings)

@spec evaluate(Jexata.Expression.t(), input(), map()) ::
  {:ok, result()} | {:error, Jexata.Error.t()}

Evaluates a compiled expression with external variable bindings.

Binding keys are variable names without the leading $, and values are JSON-like Elixir data.

evaluate(arg1, data, bindings, options)

@spec evaluate(Jexata.Expression.t(), input(), map(), keyword()) ::
  {:ok, result()} | {:error, Jexata.Error.t()}

Evaluates with a positive :max_function_depth limit for recursive calls.

evaluate!(expression, data)

@spec evaluate!(Jexata.Expression.t(), input()) :: result()

Like evaluate/2, but raises on errors.

evaluate_bounded(expression, data, options \\ [])

@spec evaluate_bounded(Jexata.Expression.t(), input(), keyword()) ::
  {:ok, result()} | {:error, Jexata.Error.t()}

Evaluates in a separate BEAM process with time, heap, reductions, and result-size limits.

Options are :timeout_ms (default 1000), :max_heap_words (default 1,000,000), :max_result_bytes (default 1,000,000), :max_reductions (disabled by default), :max_function_depth (default 1024), :regex_match_limit (default 100,000), :regex_recursion_limit (default 10,000), and :bindings (default %{}). The result-size limit uses Erlang external-term size as an estimate; it is not a JSON byte count. The process heap includes the copied input and bindings. A separate watcher enforces the timeout even if the caller exits. The optional reduction budget counts BEAM reductions, including worker setup, and is checked when work completes and periodically while it runs. It is not an exact JSONata step count.

run(source, data)

@spec run(String.t(), input()) :: {:ok, result()} | {:error, Jexata.Error.t()}

Compiles and evaluates a JSONata expression in one call.

run(source, data, bindings)

@spec run(String.t(), input(), map()) :: {:ok, result()} | {:error, Jexata.Error.t()}

Compiles and evaluates an expression with external variable bindings.

run(source, data, bindings, options)

@spec run(String.t(), input(), map(), keyword()) ::
  {:ok, result()} | {:error, Jexata.Error.t()}

Compiles and evaluates with external bindings and evaluation options.

run!(source, data)

@spec run!(String.t(), input()) :: result()

Like run/2, but raises on errors.